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Preface 



Here are your FORTRAN 77 Reference Manual Pages. You may place them 
behind your FORTRAN 77 Programmer's Guide or FORTRAN 77 Reference 
Manual or put them in the binder labelled IRIS-4D Optional Manual Pages. 
You received this binder with your IRIS-4D Series Reference Manuals. 
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NAME 

asa - interpret ASA carriage control characters 

SYNOPSIS 

asa [files] 

DESCRIPTION 

Asa interprets the output of FORTRAN programs that utilize ASA carriage 
control characters. It processes either the files whose names are given as 
arguments or the standard input if no file names are supplied. The first 
character of each line is assumed to be a control character; their meanings 
are: 

(blank) single new line before printing 

double new line before printing 

1 new page before printing 
+ overprint previous line. 

Lines beginning with other than the above characters are treated as if they 
began with ' '. The first character of a line is not printed. If any such lines 
appear, an appropriate diagnostic will appear on standard error. This pro- 
gram forces the first line of each input file to start on a new page. 
EXAMPLE 

To correctly view the output of FORTRAN programs which use ASA car- 
riage control characters, asa could be used as a filter thusly: 

a.out I asa I lpr 

and the output, properly formatted and paginated, would be directed to the 
line printer. FORTRAN output sent to a file could be viewed by: 

asa file 

SEE ALSO 

fsplit(l) 

ORIGIN 

AT&TV.3 
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NAME 

f77 - MIPS FORTRAN 77 compiler 

SYNOPSIS 

f77 [ option ] ... file ... 

DESCRIPTION f 

f77, the MIPS ucode FORTRAN 77 compiler, produces files in the follow- \^ 
ing formats: MIPS object code in MIPS extended coff format (the normal 
result), binary or symbolic ucode, ucode object files and binary or symbolic 
assembly language. 

f77 accepts several types of file arguments, file argument types are indi- 
cated by suffixes. Intermediate files and results files are usually placed in 
files whose names are generated from file by removing leading directories 
from file and substituting a different suffix. The suffixes accepted and gen- 
erated by J77 are the following: 

Suffix File Type 

/ FORTRAN source file 

. j C macro preprocessor output 

./ PFA listing file 

.m PFA intermediate file 

.o object file *- 

,p M4 preprocessor output I 

.r RATFOR source file V 

.s symbolic assembly language source 

.u ucode object file 

£ binary ucode produced by the front end 

JF FORTRAN source file 

,G binary assembly language produced by the code 

generator and the symbolic to binary assembler 

M binary ucode produced by the ucode merger 

X) binary ucode produced by the optimizer 

S binary ucode produced by the ucode object file 

splitter 

J symbol table for binary ucode, symbolic ucode, 

or binary assembly language 

JJ symbolic ucode 

file arguments whose suffixes are ./or .F are compiled, and each resulting 
object program is placed in a .o file. The .o file is deleted when a single £ 
source program is compiled and loaded all at once. V 
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RATFOR source programs, .r files, are first transformed by ratfor(l) and 
then compiled by f77 producing .o files. 

p7 always defines the C preprocessor macros sgi, mips, host_mips, unix, 
SVR3, SYSTEMSYSV, and MIPSEB to the C macro preprocessor. f77 
automatically calls the C preprocessor cpp(l), and defines the C preproces- 
sor macro LANGUAGE JFORTRAN when a /or .r file is being compiled. 

If the highest level of optimization is specified (with the -03 flag) or only 
ucode object files are to be produced (with the -j flag) each FORTRAN 77 
or RATFOR source file is compiled into a ucode object file ( .u ) . 

Symbolic assembly language source programs, .s files, are assembled and 
produce a .o file. f77 will define the C preprocessor macro 
LANGUAGEASSEMBLY vtoen a .s file is being compiled. 

file arguments whose names end with JB, .0, .5, .Af, and J primarily aid 
compiler development and are not generally used. 

If the environment variable TMPDIR is set, the value is used as the direc- 
tory to place any temporary files rather than the default Itmp. 

The following options are interpreted by f77. See W(l) for load-time 
options. 

-c Suppress the loading phase of the compilation and force an object 

file to be produced even if only one program is compiled. 

-gO Have the compiler produce no symbol table information for sym- 

bolic debugging. This is the default. 

-gl Have the compiler produce symbol table information for accurate 

but limited symbolic debugging of partially optimized code. This 
option overrides the optimization options (-O, -01, -02, -03). 

-g or -g2 

Have the compiler produce additional symbol table information 
for full symbolic debugging and not do optimizations that limit 
full symbolic debugging. These options override the optimization 
options (-O, -Ol, -02, -03). 

-g3 Have the compiler produce additional symbol table information 
for full symbolic debugging for fully optimized code. This option 
makes the debugger inaccurate. This option can be used with the 
optimization options (-O, -01, -02, -03). 

-w Suppress warning messages. 
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-pO Do not permit any profiling. If loading happens, the standard run- 
time startup routine (crtLo) is used; no profiling library is loaded. 

-p or -pi 

Set up for profiling by periodically sampling the value of the pro- 
gram counter. This option only effects the loading. When load- 
ing happens, this option replaces the standard runtime startup rou- i 
tine with the profiling runtime startup routine (mcrtl.o) and V.. 
searches the level 1 profiling library (UbprofLa) When profiling 
happens, the startup routine calls monstartupQ) and produces a 
file mon.out that contains execution-profiling data for use with the 
postprocessor prof (I). 

-00 Turn off all optimizations. 

-01 Turn on all optimizations that can be done quickly. This is the 
default. 

-Oor-02 

Invoke the global ucode optimizer. 

-03 Do all optimizations, including global register allocation. With 
this option, a ucode object file is created for each FORTRAN 77 
or RATFOR source file and left in a .u file. The newly created 
ucode object files, the ucode object files specified on the com- 
mand line, the runtime startup routine, and all of the runtime I 
libraries are ucode linked. Optimization is done on the resulting ^ 
ucode linked file and then it is linked as normal producing an 
a.out file. No resulting .o file is left from the ucode linked result 
as in previous releases, -c cannot be specified with -03. 

-feedback file 

Used with the -cord option to specify file to be used as a feed- 
back file. This file is produced by prof(\) with its -feedback 
option from an execution of the program produced by pixie (1). 
Multiple feedback files may be provided as -feedhackfitel 
-feedbackftlel... -feedbackftSm. 

-cord Run the procedure rearranges cord(l), on the resulting file after 
linking. The rearrangement is done to improve the caching and 
paging performance of the program's text. The output of cord(l) 
is left in the file specified by the -o output option or 'a.out' by 
default. At least one -feedback file must be specified. 

-j Compile the specified source programs, and leave the ucode 

object file output in .u files. Please note that this switch is non- 
standard and may not be supported across product lines. 
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-ko output 

Name the output file created by the ucode loader as output. This 
file is not removed. If this file is compiled, the object file is left in 
a file whose name consists of output with the suffix changed to a 
.o. If output has no suffix, a .o suffix is appended to output. 
Please note that this switch is non-standard and may not be sup- 
ported across product lines. 

-k Pass options that start with a -k to the ucode loader. This option 

is used to specify ucode libraries (with -kit ) and other ucode 
loader options. Please note that this switch is non-standard and 
may not be supported across product lines. 

-S Compile the specified source programs and leave the symbolic 

assembly language output in corresponding files suffixed with .s. 
If the -03 option is used, then a single file, u.out.s, is produced. 

-P Run only the C macro preprocessor and put the result for each 

source file (i.e., ./, .r, or .s file) in a corresponding i file after 
being preprocessed by the appropriate preprocessors. The .i file 
has no "#" lines in it. 

-E Run only the C macro preprocessor on the files (regardless of any 

suffix or not), and send the result to the standard output. This is 
also done for / and .r files after being processed by appropriate 
preprocessors. 

-o output 

Name the final output file output. If this option is used, the file 
a.out is undisturbed. 

-Bname=def 

-Dname Define the name to the C macro preprocessor, as if by "#define". 
If no definition, def, is given, the name is defined as " 1 ". 

-Uname Remove any initial definition of name. 

-Idir "#include" files whose names do not begin with "/" are always 
sought first in the directory of the file argument, then in direc- 
tories specified in -I options, and finally in the standard directory 
(lusr I include). 

-I This option will cause ' ^include" files never to be searched for 

in the standard directory (lusr/include). 

-G num Specify the maximum size, in bytes, of a data item that is to be 
accessed from the global pointer, num is assumed to be a decimal 
number. If num is zero, no data is accessed from the global 
pointer. The default value for num is 8 bytes. Data stored off of 
the global pointer can be accessed by the program quickly, but 
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this space is limited. Large programs may overflow the space 
accessed by the global pointer at load time. If the loader gives the 
error message Bad -G num value, recompile with a smaller 
-G num value (less than 8). Please note that this switch is non- 
standard and may not be supported across product lines. 

-v Print the passes as they execute with their arguments and their f 

input and output files. 

-V Print the version of the driver and the versions of all passes. This 

is done with the what (1) command. Please note that this switch is 
non-standard and may not be supported across product lines. 

-cpp Run the C macro preprocessor on the files before compiling. This 
is the default. 

-nocpp Do not run the C macro preprocessor on C and assembly source 
files before compiling. 

-Olimit m*m 

Specify the maximum size, in basic blocks, of a routine that will 
be optimized by the global optimizer. If a routine has more than 
this number of basic blocks it will not be optimized and a mes- 
sage will be printed. An option specifying that the global optim- 
izer is to be run (-O, -02, -03) must also be specified, num is 
assumed to be a decimal number. The default value for num is I 
500 basic blocks. 

The following options are specific for/77: 

-mp Enable the multiprocessing directives. 

-mpjkeep 

Keep the compiler generated temporary file and generate correct 
line numbers for debugging multiprocessed DO loops. This switch 
should be used with either the -mp or the -pfa switch. The saved 
file name has the form: 

$TMPDIR/P<user„subroutine_name><machine_namexpid>. If 
the TMPDIR environment variable is not set, then the file can be 
found in /tmp. 
-pfa Run the pfa(l) preprocessor to automatically discover parallelism 
in the source code. This also enables the multiprocessing direc- 
tives. There are two optional arguments: -pfa list will run pfa, 
and also produce a listing file with suffix ./ explaining which loops i 
were parallelized, and if not, why not. -pfa keep runs pfa, pro- V 
duces the listing file, and also keeps the transformed multipro- 
cessed FORTRAN intermediate file in a file with suffix .m. 
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-pfaprepass 

This option permits source code to be passed through pfa multiple 
times, pfa is run using the options found on the -pfaprepass 
option, except that no parallel compiler directives are generated. 
The output from this pre-pass is then fed back into pfa, using the 
normal options. This is occasionally useful on a few programs. In 
the vast majority of cases, multiple passes have no effect. This 
option should only be used when it has already determined that 
there is a good reason for doing so. Options to pfa appear on the 
-pfaprepass option exactly as in the -WK option. Multiple 
-pfaprepass options may be used; they are executed in left to 
right order. 

-mp_schedtype=type 

Has the same effect as putting a C$MP _SCHEDTYPE=type direc- 
tive at the beginning of the file. The supported types are simple, 
interleave, dynamic, gss, and runtime. See the FORTRAN 77 
Programmer's Guide for more details. 

-chunk=integer 

Has the same effect as putting a C$CHUNK= integer directive at 
the beginning of the file. See the FORTRAN 77 Programmer's 
Guide for more details. 

-i2 Make the default integer constants and variables short (2 bytes). 
All logical quantities will be short. 

-i4 Make the default integer constants and variables long (4 bytes). 
All logical quantities will be long. This is the default. 

-onetrip or -1 

Compile DO loops that execute at least once if reached. (FOR- 
TRAN 77 DO loops are not executed if the upper limit is smaller 
than the lower limit.) 

-66 Suppress extensions that enhance FORTRAN 66 compatibility. 

-checkjbounds 

-C Generate code for runtime subscript range checking. The default 
suppresses range checking. 

-U Do not "fold" cases. P7 is normally a case-insensitive language 
(for example a is equivalent to A). The -U option causes f77 to 
treat uppercase and lowercase separately. Note that the compiler 
only recognizes keywords in lowercase when this flag is used. 
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-u Make the default type of a variable undefined, rather than using the 
default FORTRAN rules. 

-wl Suppress the warning message for unused variables (but permit 
other warnings unless -w is specified. Please note that this switch 
is non-standard and may not be supported across product lines. ^ 
This is Oie default. i 

-wO Do not suppress the warning message for unused variables. Please 
note that this switch is non-standard and may not be supported 
across product lines. 

-w66 Suppress only FORTRAN 66 compatibility warnings messages. 

-F Apply the RATFOR preprocessor to relevant files and put the result 
in files whose names have their suffix changed to ./. (No .o files 
are created.) 

-m Apply the M4 preprocessor, m4(l), to each RATFOR source file 
before transforming it with the ratforQ) preprocessor. The tem- 
porary file used as the output of m4{\), is a .p file. This temporary 
file is removed unless the -K option is specified. 

-R Use any remaining characters in the argument as RATFOR options 
whenever processing a .r file. The temporary file used as the out- 
put of the RATFOR preprocessor is that of the last component of /" 
the source file with a / substituted for the j . This temporary file is V 
removed unless the -K option is specified. 

-automatic 

Place local variables on the runtime stack. The same restrictions 
apply for this option as they do for the automatic keyword. This is 
the default. 

-static Cause all local variables to be statically allocated. 

-noextend_source 

Cause the compiler is to restrict the range of FORTRAN source 
text from column 1 through column 72. 

-extend_source 

Pad each source line if necessary to make it 132 bytes long and 
give a warning if it exceeds 132 bytes. 

-d_lines ^ 

The djines option specifies that lines with a D in column 1 are to I 

be compiled and not to be treated as comment lines. The default is '^ 
to treat lines with a D in column 1 as comment lines. 
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-col72 Sets the source statement format to the following; 



Column 


Contents 


1-5 
6 

7-72 
73-end 


Statement label 
Continuation indicator 
Statement body 
Ignored 



-coll20 

Sets the source statement format to the following: 

Column Contents 

• ... 1-5 Statement label 

6 Continuation indicator 

7-120 Statement body 

121-end Ignored 

-oldjrl Use pre-4Dl-3.2 release record length specification for unformat- 
ted direct access file i.e. the record length specifier is interpreted as 
the number of bytes instead of number of words. 

-vms_cc 

Use VMS FORTRAN carriage control interpretation on unit 6. 
-vmsstdin 

Allow rereading from stdin after EOF has been encountered. 

-vmsendfile 

Write a VMS endfile record to the output file when ENDFILE 
statement is executed and allow subsequent reading from an input 
file after an endfile record is encountered. 

-N[qxscnl]/z/w 

Make static tables in the compiler bigger. The compiler will com- 
plain if it overflows its tables and suggest you apply one or more of 
these flags. These flags have the following meanings: 

q Maximum number of equivalenced variables. Default is 

150. 

x Maximum number of external names (common block 

names, subroutine and function names). Default is 200. 

s Maximum number of statement numbers. Default is 40 1 . 

c Maximum depth of nesting for control statements (e.g. 

DO loops). Default is 20. 
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n Maximum number of identifiers. Default is 1009. 

1 Maximum number of labels. Default is 125. 

-ZG Load the program with IRIS-4D Series compatible FORTRAN 
library routines getarg and iargc. NOTE: This option is main- 
tained for backward compatibility with older IRIS systems only 
and should not be used. Instead, the FORTRAN code should be 
modified to use the IRIS-4D Series default library routines 
getarg(3f)mdiargc(3f). 

-Wc,argl[#rg2]... 

Pass the arguments] argi to the compiler pass c. The c is one of 
[pfjusmocablKyz]. The c selects the compiler pass in the same 
way as the -t option (see -t below). Please note that this switch is 
not standard and may not be supported across product lines. 

When using either the Graphics Library (-lgl), the Shared Graphics Library 
(-lgiji), or the Distributed Graphics Library (-Idgl) you must also specify 
the Fortran Graphics Library Interface (— Ifgl) on the link line. For exam- 
ple: 

f77file.f-lfgl-lgl_s. 

Use the Shared Graphics Library (-lgljO to ensure portability across the f 
IRIS-4D product line. ^- 

The following three options when used at compile time generate various 
degrees of misaligned data in common blocks, and the code to deal with the 
misalignment. You must include these options to/77 in the compilation of 
all modules that reference or define common blocks with misaligned data. 
Failure to do so could cause core dumps (if the trap handler is not used), or 
mismatched common blocks. 

To load the system libraries capable of handling misaligned data, use the 
-L/usrAib/align switch at load time. The trap handler may be needed to 
handle misaligned data passed to system libraries not included in the 
lusrllibl align directory ($eefixade(3f) and unalignedQx)). 

-align8 Permits objects larger than 8 bits to be aligned on 8-bit boundaries. 
Using this option will have the largest impact on performance. 

-alignl6 

Permits objects larger than 16 bits to be aligned on 16-bit boun- / 
daries; 16-bit objects must still be aligned on 16-bit boundaries V 
(MC68000-like alignment rules). 
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-align32 

Permits objects larger than 32 bits to be aligned on 32-bit boun- 
daries; 16-bit objects must still be aligned on 16-bit boundaries, 
and 32-bit objects must still be aligned on 32-bit boundaries. 

The options described below primarily aid compiler development and are 
not generally used: 

-He Halt compiling after the pass specified by the character c, produc- 
ing an intermediate file for the next pass. The c can be [fjusmoca] 
(see -t below for definitions). It selects the compiler pass in the 
same way as the -t option. If this option is used, the symbol table 
file produced and used by the passes, is the last component of the 
source file with the suffix changed to J and is not removed. 
Please note that this switch is non-standard and may not be sup- 
ported across product lines. 

-K Instead of putting intermediate files in Itmp or TMPDIR, use the 
standard algorithm for generating file names with the conventional 
suffix for the type of file (for example £ file for binary ucode pro- 
duced by the front end). These intermediate files are never 
removed even when a pass encounters a fatal error. When ucode 
linking is performed and the -K option is specified the basename 
of the files created after the ucode link is u.out by default. If -ko 
output is specified, the basename of the object file is output with 
the appropriate suffix appended at the end if output has no suffix. 
Please note that this switch is non-standard and may not be sup- 
ported across product lines. 

The options -t[hpfjusmocabIrFIUMKnyz], -hpath, and -Bstring select a 
name to use for a particular pass, startup routine, or standard library. These 
arguments are processed from left to right so their order is significant. 
When the -B option is encountered, the selection of names takes place 
using the last -h and -t options. 

Therefore, the -B option is always required when using -h or -t. Sets of 
these options can be used to select any combination of names. 

Any of the -p[01] options and any of the -g[0123] options must precede all 
-B options because they can affect the location of runtimes and what run- 
times are used. 

If no -t argument has been processed before the -B then a -Bstring is 
passed to the loader to use with its -Ix arguments. 
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-t[hpfjusmocablrFIUMKnyz] 

Select the names. The names selected are those designated by the 

characters following the -t option according to the following table: 

Name Character 

include h (see note below) 

cpp p 

pfa K 

fcom f 

ujoin j 

uld u 

usplit s 

umerge m 

uopt o 

ugen c 

asO a 

asl b 

Id 1 

[m]crt[ln].o r 

libF77.a F 

libI77.a I 

libU77.a U 

libisama S 

libm.a M 

libprofl.a n 

ftoc y 

cord i 

Note: although/77 may be used to compile source files in such languages as 
C and Pascal, only the name used for the front-end of the FORTRAN com- 
piler is selected by the -tf option. 

-hpath Use path rather than the directory where the name is normally 
found. Please note that this switch is non-standard and may not be 
supported across product lines. 

-B string 

Append string to all names specified by the -t option. If no -t 
option has been processed before the ~B, the -t option is assumed 
tobe 4< hpfjusmocablrFIUMKnyz". This list designates all names. 
Invoking the compiler with a name of the form W string has the 
same effect as using a -Bstring option on the command line. f 

Other arguments are assumed to be either loader options or FORTRAN 77 V 
compatible object files, typically produced by an earlier pi run, or perhaps 
libraries of FORTRAN 77 compatible routines. These files, together with 
the results of any compilations specified, are loaded in the order given, 
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FILES 



BUGS 



producing an executable program with the default name a.out. 



/tmp/ctm* 

/usr/lib/cpp 

/usr/lib/pfa 

/usr/lib/fcom 

/usr/lib/ujoin 

/usr/bin/uld 

/usr/lib/usplit 

/usr/lib/umerge 

/usr/lib/uopt 

/usr/lib/ugen 

/usr/lib/asO 

/usr/lib/asl 

/usr/lib/cord 

/usr/lib/ftoc 

/usr/lib/crtl.o 

/usr/lib/crtn.o 

/usr/lib/mcrtl.o 

/usr/libAibc;a 

/usr/lib/libfgl.a 

/usr/lib/libfpe.a 

/usr/lib/libgl.a 

/usr/lib/libgl_s.a 

/usr/lib/libprofl.a 

/usr/lib/libF77.a 

/usr/lib/libI77_mp.a 

/usr/lib/libI77.a 

/usr/lib/libU77.a 

/usr/lib/libm.a 

/usr/lib/libisam.a 

/usr/include 

/usr/bin/ld 

/usr/bin/ratfor 

mon.out 



temporary 

C macro preprocessor 

PFA preprocessor 

FORTRAN 77 front end 

binary ucode and symbol table joiner 

ucode loader 

binary ucode and symbol table splitter 

procedure intergrator 

optional global ucode optimizer 

code generator 

symbolic to binary assembly language translator 

binary assembly language assembler and reorganizer 

procedure rearranger 

feedback file to reorder list translator 

runtime startup 

runtime startup 

startup for profiling 

standard library, see intro(3) 

FORTRAN graphics library interface 

floating point exception handier library, seefsigfpe (3f) 

graphics library 

shared graphics library 

level 1 profiling library 

FORTRAN intrinsic function library 

Multi-processing routines 

FORTRAN I/O library 

FORTRAN UNIX interface library 

math library 

indexed sequential access method library 

standard directory for "#include" files 

MIPS loader 

rational FORTRAN dialect preprocessor 

file produced for analysis by prof (I) 



The compiler attempts to continue after finding semantic errors, 
errors may result in compiler internal errors. 



These 



SEE ALSO 

as(l), asa(l), cc(l), cord(l), cpp(l), dbx(l), edge(l), fsplit(l), ftoc(l), ld(l), 
m4(l), pfa(l), pixie(l), prof(l), ratfor(l), uconv(l), what(l), fixade(3f), 
fsigfpe(3f), monstartup(3c), mp(3f), unaligned(3x). 
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IRIS-4D Series Compiler Guide 
FORTRAN 77 Programmer s Guide 
FORTRAN 77 Language Reference Manual 
POWER FORTRAN Accelerator User' s Guide 

DIAGNOSTICS f 

The diagnostics produced by f77 are intended to be self-explanatory. Occa- ^ 
sional messages can be produced by the assembler or loader. 

NOTES ■ 

The standard library, /usrflib/libc.a, is loaded by using the -lc loader option 
and not a full path name. The wrong one could be loaded if there are files 
with the name Wocjas'tring in the directories specified with the -L loader 
option or in the default directories searched by the loader. 
The handling of include directories and lihc.a is confusing. 
Since cpp does not recognize FORTRAN comments, a FORTRAN com- 
ment containing the character sequence ' 7* ' ' will result in deleting the rest 
of the FORTRAN program. The FORTRAN error message will usually 
refer to the last source line which can be very confusing. When this hap- 
pens, try the -nocpp option. 



ORIGIN 

MIPS Computer Systems 
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NAME 

fsplit - split FORTRAN or RATFOR files 
SYNOPSIS 

fsplit options files 

DESCRIPTION 

Fsplit splits the named file(s) into separate files, with one procedure per 
file. A procedure includes blockdata Junction, main, program, and subrou- 
tine program segments. Procedure X is put in file XX, X.r, or X.e depending 
on the language option chosen, with the following exceptions: main is put 
in the file MAIN.[efr] and unnamed blockdata segments in the files 
blockdataN. [efr] where N is a unique integer value for each file. 
The following options pertain: 
-f (default) Input files are FORTRAN. 
-r Input files are RATFOR. 

-s Strip FORTRAN input lines to 72 or fewer characters with trailing 
blanks removed. 

NOTES 

The characters dot (.), underbar (J, and dollar ($) are allowed as name 
characters in MIPS FORTRAN. If used in subroutine or function names 
they are also used in the file names of the created files. 

If more than one main program is encountered in the list of file (s), fsplit 
will write those after the first in files named MAINn.[efr] where the "n" is 
1 for the second main, 2 for the third, etc. 

Comment lines after an end and before the next non-comment line are dis- 
carded. Comment lines before the first non-comment line are discarded. 
SEE ALSO 

csplit(l), split(l). 

ORIGIN 

AT&T V.3 
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NAME 

ratfor - rational FORTRAN dialect 

SYNOPSIS 

ratfor [ option ... ] [ filename ... ] 

DESCRIPTION I 

Ratfor converts a rational dialect of FORTRAN into ordinary irrational V 
FORTRAN. Ratfor provides control flow constructs essentially identical to 
those in C:. 

statement grouping: 

{ statement; statement; statement } 

decision-making: 

if (condition) statement [ else statement ] 
switch (integer value) { 

case integer: statement 

[default:] statement 

) 

loops: while (condition) statement 

for (expression; condition; expression) statement 

do limits statement 

repeat statement [ until (condition) ] 

break 
next 
and some syntactic sugar to make programs easier to read and write: 

free form input: 

multiple statements/Line; automatic continuation 

comments: 

# this is a comment 

translation of relational: 

>, >=, etc., become .GT., .GE., etc. 

return (expression) 

returns expression to caller from function 

define: define name replacement 

include: include filename 

Ratfor is best used with/77(l). 
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SEE ALSO 

£77(1) 

B. W. Kernighan and P. J. Plauger, Software Tools, Addison-Wesley, 1976. 
ORIGIN 

AT&TV.3 
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NAME 

uconv - convert FORTRAN unformatted file 

SYNOPSIS 

uconv [ -ic ] [ filel ] [ -r num ] [ -o file2 ] 

DESCRIPTION 

uconv converts a FORTRAN unformatted data file either from IRIS Series 
2000 or IRIS Series 3000 FORTRAN form to IRIS-4D Series FORTRAN 
form, or vice versa, uconv allows FORTRAN users to port their otherwise 
non-portable data files opened as FORM="UNFORMATTED". 

The uconv command has the following options: 

-i Identifies the input file as an IRIS Series 2000 or IRIS Series 3000 

FORTRAN unformatted data file. This is the default. Note: the -c 
option may not be specified with this option. 

-c Identifies the input file as an IRIS-4D Series FORTRAN unformat- 

ted data file. Note: the -i option may not be specified with this 
option. 

-r num Identifies the input and output files as FORTRAN unformatted 
direct access data files, with record length num. Absence of this 
switch identifies the files as FORTRAN unformatted sequential 
access data files. 

filel The input file to be converted. Default is stdin. 

-ofile2 Specifies the output file to be created. file2 must not exist. If this 
option is absent, output is printed to stdout. 

AUTHOR 

Deborah Ryan 

NOTES 

uconv can not convert IRIS Series 2000 or IRIS Series 3000 FORTRAN 
data files opened as FORM="BINARY\ uconv can not convert IRIS Series 
2000 or IRIS Series 3000 FORTRAN data files opened as 
FORM="UNFORMATTED" with the $BINARY option. 

SEE ALSO 

Porting FORTRAN Code to IRIS-4D Series Workstations. 

ORIGIN 

Silicon Graphics, Inc. 
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NAME 

access - determine accessibility of a file 

FORTRAN SYNOPSIS 

integer function access (name, mode) 
character*(*) name, mode 

DESCRIPTION 

Path points to a path name naming a file, access checks the named file for 
accessibility according to mode using the real user ID in place of the effec- 
tive user ID and the group access list (including the real group ID ) in place 
of the effective group ID. The variable mode may include in any order and 
in any combination one or more of: 

r test for read permission 

w test for write permission 

x test for execute permission 

(blank) test for existence 

access will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] Read, write, or execute (search) permission is 

requested for a null path name. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the 

path prefix. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJiAX} . 

Too many symbolic links were encountered in 
translating the pathname. 

Write access is requested for a file on a read-only file 
system. 



[ELOOP] 

[EROFS] 

[ETXTBSY] 

[EACCES] 

[EFAULT] 



Write access is requested for a pure procedure (shared 
text) file that is being executed. 

Permission bits of the file mode do not permit the 
requested access. 

Path points outside the allocated address space for the 
process. 
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The owner of a file has permission checked with respect to the * 'owner" 
read, write, and execute mode bits. Members of the file's group other than 
the owner have permissions checked with respect to the "group" mode 
bits, and all others have permissions checked with respect to the "other" 
mode bits. 

SEE ALSO 

chmod(2), stat(2). 

DIAGNOSTICS 

If the requested access is permitted, a value of is returned. Otherwise, a 
value of -1 is returned and err no is set to indicate the error. 
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NAME 

acct - enable or disable process accounting 

FORTRAN SYNOPSIS 

integer *4 function acct (path) 
character *(*) path 

DESCRIPTION 

acct is used to enable or disable the system process accounting routine. If 
the routine is enabled, an accounting record will be written on an account- 
ing file for each process that terminates. Termination can be caused by one 
of two things: an exit call or a signal [see exit (2) and signal (2)]. The effec- 
tive user ID of the calling process must be superuser to use this call. 

path points to a pathname naming the accounting file. The accounting file 
format is given in acct(4). 

The accounting routine is enabled if path is non-zero and no errors occur 
during the system call. It is disabled if path is zero and no errors occur dur- 
ing the system call. 

acct will fail if one or more of the following are true: 

[EPERM] The effective user of the calling process is not superuser. 

[EBUS Y] An attempt is being made to enable accounting when it is 

already enabled. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] One or more components of the accounting file pathname 

do not exist. 

[EACCES] The file named by path is not an ordinary file. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] path points to an illegal address. 

SEE ALSO 

exit(2), signal(2), acct(4). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

blockproc, unblockproc, setblockproccnt, blockprocall, unblockprocall, set- 
blockproccntall - routines to block/unblock processes 

FORTRAN SYNOPSIS 

integer*4 function blockproc (pid) 
integer *4 pid; 

integer*4 function unblockproc (pid) 
integer *4 pid; 

integer*4 function setblockproccnt (pid, count) 
integer *4 pid; 
integer*4 count; 

integer *4 function blockprocall (pid) 
integer *4 pid; 

integer*4 function unblockprocall (pid) 
integer*4pid; 

integer*4 function setblockproccntall (pid, count) 
integer*4 pid; 
integer*4 count; 

DESCRIPTION f 

These routines provide a complete set of blocking/unblocking capabilities I 
for processes. Blocking is implemented with a counting semaphore in the v 
kernel. Each call to blockproc decrements the count. When the count 
becomes negative, the process is suspended. When unblockproc is called, 
the count is incremented. If the count becomes non-negative (>= 0), the 
process is restarted. This provides both a simple, race free synchronization 
ability between two processes and a much more powerful capability to syn- 
chronize multiple processes. 

In order to guarantee a known starting place, the setblockproccnt function 
may be called, which will force the semaphore count to the value given by 
count. New processes have their semaphore zeroed. Normally, count 
should be set to 0. If the resulting block count is greater than or equal to 
zero and the process is currently blocked, it will be unblocked. If the result- 
ing block count is less than zero, the process will be blocked. Using this, a 
simple rendezvous mechanism can be set up. If one process wants to wait 
for n other processes to complete, it could set its block count to -n. This 
would immediately force the process to block. Then as each process f 
finishes, it unblocks the waiting process. When the n'th process finishes the V 
waiting process will be awakened. 
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The blockprocall, unblockprocall, and setblockproccntall system calls per- 
form the same actions as blockproc, unblockproc, and setblockproccnt, 
respectively, but act on all processes in the given process' share group. A 
share group is a group of processes created with the sproc(2) system call. If 
a process does not belong to a share group, the effect of the plural form of a 
call will be the same as that of the singular form. 

A process may block another provided that standard UNIX permissions are 
satisfied. 

A process may determine whether another is blocked by using the prctl(2) 
system call. It should be noted that since other processes may unblock the 
subject process at any time, the answer should be interpreted as a snapshot 
only. 

These routines will fail and no operation will be performed if one or more 
of the following are true: 

[ESRCH] The pid specified does not exist. 

[EPERM] The caller is not operating on itself, its effective user ID 

is not super-user, and its real or effective user ID does 
not match the real or effective user ID of the target pro- 
cess. 

[EINVAL] The count value that would result from the requested 

blockproc, unblockproc or setblockproccnt is less than 
PRJVIINBLOCKCNT or greater than 

PR_M AXBLOCKCNT as defined in syslprctl h . 
SEE ALSO 

sproc(2), prctl(2). 

DIAGNOSTICS 

Upon successful completion, is returned. Otherwise, a value of -1 is 
returned to the calling process, and errno is set to indicate the error. When 
using the blockprocall, unblockprocall, and setblockproccntall calls, an 
error may occur on any of the processes in the share group. These calls will 
attempt to perform the given action on each process in the share group 
despite earlier errors, and set errno to indicate the error of the last failure to 
occur. 
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NAME 

brk, sbrk - change data segment space allocation 

FORTRAN SYNOPSIS 

integer *4 function brk (endds) 
character * (*) endds 

character * 4096 function sbrk (incr) 
integer *4 incr 

DESCRIPTION 

brk and sbrk are used to change dynamically the amount of space allocated 
for the calling process's data segment [see exec(2)]. The change is made 
by resetting the process's break value and allocating the appropriate amount 
of space. The break value is the address of the first location beyond the end 
of the data segment. The amount of allocated space increases as the break 
value increases. Newly allocated space is set to zero. If, however, the 
same memory space is reallocated to the same process its contents are 
undefined. 

brk sets the break value to endds and changes the allocated space accord- 
ingly. 

Sbrk adds incr bytes to the break value and changes the allocated space 
accordingly. Incr can be negative, in which case the amount of allocated 
space is decreased. 

brk and sbrk will fail without making any change in the allocated space if 
one or more of the following are true: 

[ENOMEM] Such a change would result in more space being 
allocated than is allowed by the system-imposed 
maximum process size {PROCSIZEMAX} . [see 
intro(2)]. 

[EAGAIN] There is insufficient amount of operating system 

memory to hold the data structures needed to 
describe the requested space. This is likely a tem- 
porary failure. 

SEE ALSO 

exec(2), intro(2), shmop(2), getrlimit(2), ulimit(2), end(3C). 

DIAGNOSTICS 

Upon successful completion, brk returns a value of and sbrk returns the 
old break value. Otherwise, a value of -1 is returned and err no is set to 
indicate the error. 
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NAME 

chdir - change working directory 

FORTRAN SYNOPSIS 

integer function chdir (path) 
character*(*) path 

DESCRIPTION 

Path points to the path name of a directory, chdir causes the named direc- 
tory to become the current working directory, the starting point for path 
searches for path names not beginning with /. 

chdir will fail and the current working directory will be unchanged if one or 
more of the following are true: 

[ENOTDIR] A component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for any component of the 

path name. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[ELOOP] A path name lookup involved too many symbolic 

links. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX) y ox a path- 
name component is longer than {NAME_MAX} . 
SEE ALSO 

chroot(2), getwd(3C). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

chown, fchown - change owner and group of a file (System V and 4.3BSD) 

FORTRAN SYNOPSIS 

integer *4 function chown (path, owner, group) 
character * (*) path 
integer *4 owner, group 

integer *4 function fchown (fd, owner, group) 
integer *4 fd, owner, group 

DESCRIPTION 

Path points to a path name naming a file, mdfd refers to the file descriptor 
associated with a file. The owner ID and group ID of the named file are set 
to the numeric values contained in owner and group respectively. 

Only processes with effective user ID equal to the file owner or super-user 
may change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set- 
group-ID bits of the file mode, 04000 and 02000 respectively, will be 
cleared. Note that this has the side-effect of disabling mandatory file/record 
locking. 

The only difference between the System V and 4.3BSD versions is that the 
4.3BSD versions allow either the owner or group ID to be left unchanged by /" 
specifying it as a -1. V 

chown will fail and the owner and group of the named file will remain 
unchanged if one or more of the following are true: 
[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the 

path prefix. 

[EPERM] The effective user ID does not match the owner of the 

file and the effective user ID is not super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[ELOOP] A path name lookup involved too many symbolic 

links. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJAAK} . 
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fchown will fail if: 

[EBADF] Fd does not refer to a valid descriptor. 

[EINVAL] Fd refers to a socket, not a file. 

SEE ALSO 

chmod(2), fchmod(2). 

chown(l) in theUser's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and err no is set to indicate the error. 
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SEE ALSO 

chdir(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

chroot - change root directory 

FORTRAN SYNOPSIS 

integer *4 function chroot (path) 
character *(*) path 

DESCRIPTION 

Path points to a path name naming a directory, chroot causes the named 

directory to become the root directory, the starting point for path searches 

for path names beginning with /. The user's working directory is unaffected 

by the chroot system call. 

The effective user ID of the process must be super-user to change the root 

directory. 

The .. entry in the root directory is interpreted to mean the root directory 

itself. Thus, .. cannot be used to access files outside the subtree rooted at 

the root directory. 

chroot will fail and the root directory will remain unchanged if one or more 

of the following are true: 

[ENOTDIR] Any component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EPERM] The effective user ID is not super-user. ^ 

[EFAULT] Path points outside the allocated address space of the 

process. 
[EINTR] A signal was caught during the chroot system call. 

[ENOIJNK] Path points to a remote machine and the link to that 

machine is no longer active. 
[EMULTIHOP] Components of path require hopping to multiple remote 

machines. 
[ELOOP] A path name lookup involved too many symbolic links. 

[ENAMETOOLONG] 

A component of a path name exceeded 255 characters, or 
an entire path name exceeded 1023 characters. 
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NAME 

close - close a file descriptor 

FORTRAN SYNOPSIS 

integer*4 function close (Hides) 
integer*4 fildes 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dupjcntl, or pipe 
system call, close closes the file descriptor indicated by fildes. All out- 
standing record locks owned by the process (on the file indicated by fildes) 
are removed. 

If a STREAMS [see intro(2)] file is closed, and the calling process had previ- 
ously registered to receive a SIGPOLL signal [see signal(2) and sigset(2)] 
for events associated with that file [see I.SETSIG in streamio(7)], the calling 
process will be unregistered for events associated with the file. The last 
close for a stream causes the stream associated with fildes to be dismantled. 
If 0_NDELAY is not set and there have been no signals posted for the 
stream, close waits up to 15 seconds, for each module and driver, for any 
output to drain before dismantling the stream. If the 0_NDELAY flag is set 
or if there are any pending signals, close does not wait for output to drain, 
and dismantles the stream immediately. 

The named file is closed unless one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EINTR] A signal was caught during the close system call. 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), intro(2), open(2), pipe(2), signal(2), sig- 
set(2). 

streamio{7) in the System Administrator' s Reference Manual. 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

creat - create a new file or rewrite an existing one 

FORTRAN SYNOPSIS 

integer *4 function creat (path, mode) 

character *(*) path ^ 

integer *4 mode I 

DESCRIPTION 

creat creates a new ordinary file or prepares to rewrite an existing file 
named by the path name pointed to by path . 

If the file exists, the length is truncated to and the mode and owner are 
unchanged. Otherwise, the file's owner ID is set to the effective user ID, of 
the process the group ID is set to the effective group ID, of the process or to 
the group ID of the directory in which the file is being created. This is 
determined as follows: 

If the underlying filesystem was mounted with the BSD file crea- 
tion semantics flag [see fstah(4)] or the S JSGID bit is set [see 
chmod(2)] on the parent directory, then the group ID of the new 
file is set to the group ID of the parent directory, otherwise it is set 
to the effective group ID of the calling process. 

The low-order 12 bits of the file mode are set to the value of mode modified 

as follows: 

All bits set in the process's file mode creation mask are cleared 

[see umask(2)]. 

The "sticky bit" of the mode is cleared [see chrnod(2)]. 

Upon successful completion, a write-only file descriptor is returned and the 

file is open for writing, even if the mode does not permit writing. A new 

file may be created with a mode that forbids writing. 

The file pointer used to mark the current position within the file is set to the 

beginning of the file. 

The new file descriptor is set to remain open across execve(2) system calls 

[see/cnrf(2)]. 

There is a system enforced limit on the number of open file descriptors per 

process {OPENJ4AX}, whose value is returned by the getdtablesize(2) 

function. 

creat fails if one or more of the following are true: 
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[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EACCES] Search permission is denied on a component of the 

path prefix. 

[ENOENT] The path name is null. 

[EACCES] The file does not exist and the directory in which the 

file is to be created does not permit writing. 

[EROFS] The named file resides or would reside on a read-only 

file system. 

[ETXTBSY] The file is a pure procedure (shared text) file that is 

being executed. 

[EACCES] The file exists and write permission is denied. 

[EISDIR] The named file is an existing directory. 

[EMFILE] The system imposed limit for open file descriptors per 

process {OPEN MAX} has already been reached. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[ENFILE] The system file table has exceeded {NFILEJiAXj 

concurrently open files. 

[EAGAIN] The file exists, mandatory file/record locking is set, 

and there are outstanding record locks on the file [see 
chmod(2)]. 

[ENOSPC] The file system is out of inodes. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJiAX} . 

[EOPNOTSUPP] An attempt was made to open a socket (not currently 
supported). 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), lseek(2), open(2), read(2), umask(2), 
write(2), fstab(4). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely the file 
descriptor, is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 
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NAME 

dup - duplicate an open file descriptor 

FORTRAN SYNOPSIS 

integer *4 function dup (fildes) 
integer *4 fildes 
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DESCRIPTION 

Fildes is a descriptor obtained from a creat, open, dup, fcntl, pipe, socket, 
or socketpair system call, dup returns a new descriptor having the follow- 
ing in common with the original: 

Refers to same object as the original descriptor. 

Same file pointer (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/write). 

Same descriptor status flags (i.e., both descriptors share the same 

status flags). 

Shares any file locks. 
The new descriptor is set to remain open across exec system calls [see 
fcntlQ)]. 

The descriptor returned is the lowest one available. 

dup will fail if one or more of the following are true: I 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] The system imposed limit for open file descriptors per 

process {OPENJ4AX} has already been reached. 

SEE ALSO 

close(2), creat(2), exec(2), fcntl(2), intro(2), open(2), pipe(2), lockf(3C). 

DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descrip- 
tor, is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 
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NAME 

exit, _exit - terminate process 

FORTRAN SYNOPSIS 
integer status 
call exit (status) 

DESCRIPTION 

exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. If the pro- 
cess is sharing file descriptors via an sproc, other members of the share 
group do NOT have their file descriptors closed. 

If the parent process of the calling process is executing a wait, it is notified 
of the calling process's termination and the low order eight bits (i.e., bits 
0377) of status are made available to it [see wait (2)]. 

If the parent process of the calling process is not executing a wait, and the 
parent process is not ignoring SIGCLD, the calling process is transformed 
into a zombie process. A zombie process is a process that only occupies a 
slot in the process table. It has no other space allocated either in user or 
kernel space. The process table slot that it occupies contains the time 
accounting information [see <sys/proc.h>] to be used by times. 

The parent process ID of all of the calling processes' existing child 
processes and zombie processes is set to 1. This means the initialization 
process [see intro(2)] inherits each of these processes. 

If the process belongs to a share group, it is removed from that group. Its 
stack segment is deallocated and removed from the share group's virtual 
space. All other virtual space that was shared with the share group is left 
untouched. If the prctl (PRSETEXITSIG) option has been enabled for the 
share group, than the specified signal is sent to all remaining share group 
members. 

Each attached shared memory segment is detached and the value of 
shm_nattach in the data structure associated with its shared memory 
identifier is decremented by 1. 

For each semaphore for which the calling process has set a semadj value 
[see semop(2)], that semadj value is added to the semval of the specified 
semaphore. 

If the process has a process, text, or data lock, an unlock is performed [see 
plock(2)]. If the process has any pages locked, they are unlocked [see 
mpin(2)]. 
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An accounting record is written on the accounting file if the system's 
accounting routine is enabled [see acct(2)]. 

If the calling process is a process group leader (its process ID matches its 
process group ID ), and it became a process group leader by invoking the 
setpgrp(2) function, and it is a terminal group leader (has an associated 
controlling terminal), then the SIGHUP signal is sent to each process that I 
has a process group ID equal to that of the calling process. ^- 

If the calling process is a process group leader (its process ID matches its 
process group ID ), and it became a process group leader by invoking the 
setpgid(2) function, and it is a session leader [see setsid(2) ], and it has an 
associated controlling terminal, then the SIGHUP signal is sent to each pro- 
cess in the foreground process group of the controlling terminal belonging 
to calling process. 

If the calling process is a process group leader (its process ID matches its 
process group ID ), and it became a process group leader by invoking the 
setpgrp(2) function, no signal is sent. 

In all cases, if the calling process is a process group leader and has an asso- 
ciated controlling terminal, the controlling terminal is disassociated from 
the process allowing it to be acquired by another process group leader. 

Any mapped files are closed and any written pages flushed to disk. 

A death of child signal is sent to the parent. 

The C function exit causes all file streams to be closed unless one has done 
an sproc which causes the file streams to simply be flushed. The function 
_exit circumvents all cleanup. 

SEE ALSO 

acct(2), intro(2), mmap(2), mpin(2), plock(2), prctl(2), semop(2), 
setpgid(2), setpgrp(2), signal(2), sigset(2), sigaction(2), sigprocmask(2), 
sigvec(3B), sigblock(3B), sigsetmask(3B), sproc(2), wait(2). 

WARNING 

See WARNING in signal(2). 

DIAGNOSTICS 

None. There can be no return from an exit system call. 
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NAME 

fcntl - file and descriptor control 

FORTRAN SYNOPSIS 

integer *4 function fcntl (fildes, cmd, arg) 
integer *4 fildes, cmd, arg 

DESCRIPTION 

fcntl provides for control over open descriptors. Fildes is an open descrip- 
tor obtained from a creat, open, dup, fcntl, pipe, socket, or socketpair sys- 
tem call. 

The commands available are: 

F_DUPFD Return a new descriptor as follows: 

Lowest numbered available descriptor greater than or 
equal to the third argument, arg, taken as an integer of 
type int. 

Refers to the same object as the original descriptor. 

Same file pointer as the original file (i.e., both file descrip- 
tors share one file pointer). 

Same access mode (read, write or read/write). 

Same descriptor status flags (i.e., both descriptors share 
the same status flags). 

Shares any file locks. 

The close-on-exec flag ( FDCLOEXEC) associated with 
the new descriptor is cleared to keep the file open across 
calls to the exec (2) family of functions. 

FGETFD Get the file descriptor flags associated with the descriptor 

fildes. If the FDCLOEXEC flag is the descriptor will 
remain open across exec, otherwise the descriptor will be 
closed upon execution of exec. 

F__SETFD Set the file descriptor flags for fildes. Currently the only 

flag implemented is FDCLOEXEC. Note: this flag is a 
per-process and per-descriptor flag; setting or clearing it 
for a particular descriptor will not affect the flag on 
descriptors copied from it by a dup (2) or FDUPFD 
operation, nor will it affect the flag on other processes 
instances of that descriptor. 
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F GETLK 



F SETLK 



Get file status flags and file access modes. The file access 
modes may be extracted from the return value using the 
mask O^ACCMODE. 

Set file status flags to the third argument, org, taken as 
type int. Only the following flags can be set [see 
fcntldS)]: FAPPEND, FSYNC, FNDELAY, FNONBLOCK, 
and FASYNC. FAPPEND is equivalent to 0_APPEND; 
FSYNC is equivalent to OJSYNC; FNDELAY is 
equivalent to 0_NDELAY; and FNONBLOCK is 
equivalent to OJVONBLOCK. FASYNC is equivalent to 
calling ioctl with the FIOASYNC command. This enables 
the SIGIO facilities and is currently supported only on 
sockets. 

Since the descriptor status flags are shared with descrip- 
tors copied from a given descriptor by a dup{2) or 
FJ)UPFD operation, and by other processes instances of 
that descriptor a FJSETFL operation will affect those 
other descriptors and other instances of the given descrip- 
tors as well. For example, setting or clearing the FNDE- 
LAY flag will logically cause an FIONBIO ioctl(2) to be 
performed on the object referred to by that descriptor. 
Thus all descriptors referring to that object will be 
affected. 

Flags not understood for a particular descriptor are 
silently ignored. 

Get the first lock which blocks the lock description given 
by the variable of type struct flock pointed to by org. The 
information retrieved overwrites the information passed 
to fcntl in the flock structure. If no lock is found that 
would prevent this lock from being created, then the 
structure is passed back unchanged except for the lock 
type which will be set to FJJNLCK. 

Set or clear a file segment lock according to the variable 
of type struct flock pointed to by org [see/c/if/(5)]. The 
cmd F J5ETLK is used to establish read (FJ&DLCK) and 
write (F_WRLCK) locks, as well as remove either type of 
lock (FJJNLCK). If a read or write lock cannot be set 
fcntl will return immediately with an error value of -1. 
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F_SETLKW This cmd is the same as F_SETLK except that if a read or 
write lock is blocked by other locks, the process will sleep 
until the segment is free to be locked. 

FCHKFL This flag is used internally by FJSETFL to check the 

legality of file flag changes. 

FGETOWN Used by sockets: get the process ID or process group 
currently receiving SIGIO and SIGURG signals; process 
groups are returned as negative values. 

FSETOWN Used by sockets: set the process or process group to 
receive SIGIO and SIGURG signals; process groups are 
specified by supplying arg as negative, otherwise arg is 
interpreted as a process ID. 

A read lock prevents any process from write locking the protected area. 
More than one read lock may exist for a given segment of a file at a given 
time. The file descriptor on which a read lock is being placed must have 
been opened with read access. 

A write lock prevents any process from read locking or write locking the 
protected area. Only one write lock may exist for a given segment of a file 
at a given time. The file descriptor on which a write lock is being placed 
must have been opened with write access. 

The structure flock describes the type (Ijype), starting offset {I whence), 
relative offset (Ijstart), size {I Jen), process id (lj)id), and RFS system id 
(Ijsysid) of the segment of the file to be affected. The process id and sys- 
tem id fields are used only with the F_GETLK cm d to return the values for a 
blocking lock. Locks may start and extend beyond the current end of a file, 
but may not be negative relative to the beginning of the file. A lock may be 
set to always extend to the end of file by setting I Jen to zero (0). If such a 
lock also has Ijvhence and Ijstart set to zero (0), the whole file will be 
locked. Changing or unlocking a segment from the middle of a larger 
locked segment leaves two smaller segments for either end. Locking a seg- 
ment that is already locked by the calling process causes the old lock type 
to be removed and the new lock type to take effect. All locks associated 
with a file for a given process are removed when a file descriptor for that 
file is closed by that process or the process holding that file descriptor ter- 
minates. Locks are not inherited by a child process in afork(2) system call. 

When mandatory file and record locking is active on a file, [see chmod(2)] t 
read and write system calls issued on the file will be affected by the record 
locks in effect. 
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fcritl will fail if one or more of the following are true: 



c 



[EBADF] Fildes is not a valid open file descriptor. 

[EINVAL] Cmd is F_DUPFD. arg is either negative, or greater than 

or equal to the maximum number of open file descriptors 
allowed each user [see getdtahlesize(2)]. 

[EMFILE] Cmd is F_DUPFD and {OPEN MAX) file descriptors are 

currently in use by this process, or no file descriptors 
greater than or equal to arg are available. 

[EINVAL] Cmd is F.GETLK, FJSETLK, or SETLKW and arg or the 

data it points to is not valid. 

[EAGAIN] Cmd is F_SETLK the type of lock (Ijype) is a read 

(FJIDLCK) lock and the segment of a file to be locked is 
already write locked by another process or the type is a 
write (F__WRLCK) lock and the segment of a file to be 
locked is already read or write locked by another pro- 
cess. 

[ENOLCK] Cmd is FJSETLK or F_SETLKW, the type of lock is a read 

or write lock, and there are no more record locks avail- 
able (too many file segments locked) because the system 
maximum { FLOCK JdAX} [see intro(2)] 9 has been 
exceeded. 

[EINTR] Cmd is F„SETLKW and a signal interrupted the process 

while it was waiting for the lock to be granted. 

[EDEADLK] Cmd is F.SETLKW, the lock is blocked by some lock 

from another process, and putting the calling-process to 
sleep, waiting for that lock to become free, would cause 
a deadlock. 

[EFAULT] Cmd is F_SETLK, arg points outside the program address 

space. 

[ESRCH] Cmd is FJSETOWN and no process can be found 

corresponding to that specified by arg. 

SEE ALSO 

close(2), creat(2), dup(2), exec(2), fork(2), getdtablesize(2), intro(2), 
open(2), pipe(2), fcntl(5). / 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 
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F_DUPFD 
F_GETFD 
F_SETFD 
F_GETFL 
F_SETFL 
F_GETLK 
FJSETLK 
F_SETLKW 
F_GETOWN 
F_SETOWN 
Otherwise, a value of - 



A new file descriptor. 

Value of flag (only the low-order bit is defined). 
Value other than -1. 
Value of file flags. 
Value other than - 1 . 
Value other than -1. 
Value other than -1. 
Value other than -1. 
Pid of socket owner. 
Value other than -1. 
1 is returned and errno is set to indicate the error. 
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NAME 

fork - create a new process 

FORTRAN SYNOPSIS 

integer function fork() 

DESCRIPTION f 

fork causes creation of a new process. The new process (child process) is |^ 
an exact copy of the calling process (parent process). This means the child 
process inherits the following attributes from the parent process: 

environment 

close-on-exec flag [see exec (2)] 

signal handling settings (i.e., SIGJDFL, SIGJGN, SIGJHOLD, 

function addresses and signal masks) 

set-user-ID mode bit 

set-group-ID mode bit 

profiling on/off status 

debugger trailing status 

nice value [see nice (2)] 

all attached shared memory segments [see shmop(2)] 

all mapped files [see mmap(2)] 

non-degrading priority [see schedctl{2)] 

process group ID ^ 

tty group ID [see exit (2)] ^ 

current working directory 

root directory 

file mode creation mask [see umask{2)] 

file size limit [see ulimit(2)] 

The child process differs from the parent process in the following ways: 
The child process has a unique process ID, 
The child process has a different parent process ID (i.e., the pro- 
cess ID of the parent process). 

The child process has its own copy of the parent's file descriptors. 
Each of the child's file descriptors shares a common file pointer 
with the corresponding file descriptor of the parent. 

File locks previously set by the parent are not inherited by the 
child [see/cnri(2)]. 

All semadj values are cleared [see semap Q)]. | 

Process locks, text locks and data locks are not inherited by the 
child [see plock(2)]. 
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The set of signals pending to the parent is not inherited by the 
child. 

Page locks are not inherited [see mpin(2)]. 

The child process's utirne, stime, cutime, and cstime are set to 0. 
The time left until an alarm clock signal is reset to 0. 

The time left until an itimer signal is reset to 0. 

The child will not inherit the ability to make graphics calls. The 
child must establish itself as a graphics process by invoking the 
winopen(3G) (or ginit(3G)) call. Otherwise the child process may 
receive a segmentation fault upon attempting to make a graphics 
call. 

The share mask is set to [see sproc(2)]. 

fork will fail and no child process will be created if one or more of the fol- 
lowing are true: 

[EAGAIN] The system -imposed limit on the total number of 

processes under execution, {NPROQ [see intro(2)] i 
would be exceeded. 

[EAGAIN] The system -imposed limit on the total number of 

processes under execution by a single user 
{CHILD MAX} [see intro(2)l would be exceeded. 

[EAGAIN] Amount of system memory required is temporarily una- 

vailable. 

SEE ALSO 

exec(2), intro(2), mmap(2), nice(2), pcreate(3C), plock(2), ptrace(2), 
schedctl(2), semop(2), shmop(2), signal(2), sigset(2), sigaction(2), 
signal(3B), sigvec(3B), sproc(2), times(2), ulimit(2), umask(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, fork returns a value of to the child process 
and returns the process ID of the child process to the parent process. Other- 
wise, a value of -1 is returned to the parent process, no child process is 
created, and errno is set to indicate the error. 
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NAME 

getdents - read directory entries and put in a file system independent format 

FORTRAN SYNOPSIS 

integer *4 function getdents (fildes, buf, nbyte) 
integer *4 fildes 
character * (*) buf 
integer *4 nbyte 

DESCRIPTION 

Fildes is a file descriptor obtained from an open(2) or dup(2) system call. 

getdents attempts to read nbyte bytes from the directory associated with 
fildes and to format them as file system independent directory entries in the 
buffer pointed to by buf. Since the file system independent directory entries 
are of variable length, in most cases the actual number of bytes returned 
will be strictly less than nbyte . 

The file system independent directory entry is specified by the dirent struc- 
ture. For a description of this see dirent(4). 

On devices capable of seeking, getdents starts at a position in the file given 
by the file pointer associated with fildes. Upon return from getdents, the file 
pointer is incremented to point to the next directory entry. 

This system call was developed in order to implement the readdir (3C) rou- 
tine [for a description see directory (3C)], and should not be used for other 
purposes. 

getdents will fail if one or more of the following are true: 
[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 

[EINVAL] nbyte is not large enough for one directory entry. 

[ENOENT] The current file pointer for the directory is not located at 

a valid entry. 

[ENOIINK] Fildes points to a remote machine and the link to that 

machine is no longer active. 

[ENOTDIR] Fildes is not a directory. 

[EIO] An I/O error occurred while accessing the file system. 

SEE ALSO 

directory(3C), dirent(4). 
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DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating 
the number of bytes actually read. A value of indicates the end of the 
directory has been reached. If the system call failed, a -1 is returned and 
errno is set to indicate the error. 
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NAME 

gethostid, sethostid - get/set unique identifier of current host 

FORTRAN SYNOPSIS 

integer *4 function gethostid () 

subroutine sethostid () ^ 

integer *4 hostid V 

DESCRIPTION 

Sethostid establishes a 32-bit identifier for the current processor that is 
intended to be unique among all UNIX systems in existence. This is nor- 
mally a DARPA Internet address for the local machine. This call is allowed 
only to the super-user and is normally performed at boot time. 

Gethostid returns the 32-bit identifier for the current processor. 

SEE ALSO 

hostid(l), gethostname(2) 

BUGS 

32 bits for the identifier is too small. 
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NAME 

gethostname, sethostname - get/set name of current host 
FORTRAN SYNOPSIS 

integer function gethostname (name, namelen) 

character *1 name (namelen) 

integer namelen 

DESCRIPTION 

Gethostname returns the standard host name for the current processor, as 
previously set by sethostname. The parameter namelen specifies the size of 
the name array. The returned name is null-terminated unless insufficient 
space is provided. 

Sethostname sets the name of the host machine to be name, which has 
length namelen. This call is restricted to the super-user and is normally 
used only when the system is bootstrapped. 

RETURN VALUE 

If the call succeeds a value of is returned. If the call fails, then a value of 
-1 is returned and an error code is placed in the global location errno. 
ERRORS 

The following errors may be returned by these calls: 

[EFAULT] The name or namelen parameter gave an invalid address. 

[EPERM] The caller tried to set the hostname and was not the 

super-user. 

[EINVAL] The namelen parameter was too large. 

SEE ALSO 

gethostid(2) 

BUGS 

Host names are limited to MAXHOSTNAMELEN (from <sys/param.h>) 
characters, currently 64. 
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NAME 

getpid, getpgrp, getppid - get process, process group, and parent process 

IDs 

FORTRAN SYNOPSIS 

integer function getpid() g- 

integer function getpgrpO I 

integer function getppidO 

DESCRIPTION 

getpid returns the process ID of the calling process. 

getpgrp returns the process group ID of the calling process. 

getppid returns the parent process ID of the calling process. 

SEE ALSO 

exec(2), fork(2), intro(2), setpgrp(2), signal(2). 
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NAME 

getsockopt, setsockopt - get and set options on sockets 
FORTRAN SYNOPSIS 

subroutine getsockopt (s, level, optname, optval, optlen) 

integer *4 s, level, optname 

character * (*) optval 

integer *4 optlen 

subroutine setsockopt (s, level, optname, optval, optlen) 
integer *4 s, level, optname 
character * (*) optval 
integer *4 optlen 

DESCRIPTION 

Getsockopt and setsockopt manipulate options associated with a socket. 
Options may exist at multiple protocol levels; they are always present at the 
uppermost "socket" level. 

When manipulating socket options the level at which the option resides and 
the name of the option must be specified. To manipulate options at the 
1 'socket' ' level, level is specified as SOL_SOCKET. To manipulate options 
at any other level the protocol number of the appropriate protocol control- 
ling the option is supplied. For example, to indicate that an option is to be 
interpreted by the TCP protocol, level should be set to the protocol number 
of TCP; see getprotoent(3N). 

The parameters optval and optlen are used to access option values for set- 
sockopt. For getsockopt they identify a buffer in which the value for the 
requested option(s) are to be returned. For getsockopt, optlen is a value- 
result parameter, initially containing the size of the buffer pointed to by 
optval, and modified on return to indicate the actual size of the value 
returned. If no option value is to be supplied or returned, optval may be 
supplied as 0. 

Optname and any specified options are passed uninterpreted to the appropri- 
ate protocol module for interpretation. The include file <sy si socket. h> con- 
tains definitions for ' 'socket" level options, described below. Options at 
other protocol levels vary in format and name; consult the appropriate 
entries in section (4P). 

Most socket-level options take an int parameter for optvaL For setsockopt, 
the parameter should non-zero to enable a boolean option, or zero if the 
option is to be disabled. SOJLINGER uses a struct linger parameter, 
defined in <sysl socket. h>, which specifies the desired state of the option 
and the linger interval (see below). 
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The following options are recognized at the socket level. Except as noted, 
each may be examined with getsockopt and set with setsockopt. 

SO_DEBUG toggle recording of debugging information 

SO_REUSEADDR toggle local address reuse 

SOJCEEPALIVE toggle keep connections alive I 

SO_DONTROUTE toggle routing bypass for outgoing messages V 

SOJLINGER linger on close if data present 

SO_BROADC AST toggle permission to transmit broadcast messages 

SO_OOBINLINE toggle reception of out-of-band data in band 

SO_SNDBUF set buffer size for output 

SO_RCVBUF set buffer size for input 

SO_TYPE get the type of the socket (get only) 

SO_ERROR get and clear error on the socket (get only) 

SO_DEBUG enables debugging in the underlying protocol modules. 
SO_REUSEADDR indicates that the rules used in validating addresses sup- 
plied in a bind(2) call should allow reuse of local addresses. 
SOJCEEP ALIVE enables the periodic transmission of messages on a con- 
nected socket. Should the connected party fail to respond to these mes- 
sages, the connection is considered broken and processes using the socket 
are notified via a SIGPIPE signal. SOJDONTROUTE indicates that outgo- / 
ing messages should bypass the standard routing facilities. Instead, mes- V 
sages are directed to the appropriate network interface according to the net- 
work portion of the destination address. 

SOJLINGER controls the action taken when unsent messages are queued 
on socket and a close(2) is performed. If the socket promises reliable 
delivery of data and SOJLINGER is set, the system will block the process 
on the close attempt until it is able to transmit the data or until it decides it 
is unable to deliver the information (a timeout period, termed the linger 
interval, is specified in the setsockopt call when SOJLINGER is requested). 
If SOJLINGER is disabled and a close is issued, the system will process the 
close in a manner that allows the process to continue as quickly as possible. 
The option SO_BROADCAST requests permission to send broadcast 
datagrams on the socket. Broadcast was a privileged operation in earlier 
versions of the system. With protocols that support out-of-band data, the 
SO_OOBINLINE option requests that out-of-band data be placed in the 
normal data input queue as received; it will then be accessible with recv or I 
read calls without the MSG„OOB flag. SO_SNDBUF and SO.RCVBUF V. 
are options to adjust the normal buffer sizes allocated for output and input 
buffers, respectively. The buffer size may be increased for high-volume 
connections, or may be decreased to limit the possible backlog of incoming 

April 1990 -2- Version 3.0 



GETSOCKOPT(2) Silicon Graphics GETSOCKOPT(2) 

data. The system places an absolute limit on these values. Finally, 
SO_TYPE and SO_ERROR are options used only with setsockopt. 

SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is 
useful for servers that inherit sockets on startup. SO_ERROR returns any 
pending error on the socket and clears the error status. It may be used to 
check for asynchronous errors on connected datagram sockets or for other 
asynchronous errors. 

RETURN VALUE 

A is returned if the call succeeds, -1 if it fails. 
ERRORS 

The call succeeds unless: 

[EBADF] The argument s is not a valid descriptor. 

[ENOTSOCK] The argument s is a file, not a socket. 

PENOPROTOOPT] The option is unknown at the level indicated. 

[EFAULT] The address pointed to by optval is not in a valid 

part of the process address space. For getsockopt, 
this error may also be returned if optlen is not in a 
valid part of the process address space. 
SEE ALSO 

ioctl(2), socket(2), getprotoent(3N) 
BUGS 

Several of the socket options should be handled at lower levels of the sys- 
tem. 
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NAME 

getuid, geteuid, getgid, getegid - get real user, effective user, real group, 
and effective group IDs 

FORTRAN SYNOPSIS 

integer function getuid() ^ 

integer*2 function geteuidO f 

integer function getgidQ 
integer*2 function getegidQ 

DESCRIFHON 

getuid returns the real user ID of the calling process. 

geteuid returns the effective user ID of the calling process. 

getgid returns the real group ID of the calling process. 

getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

ioctl - control device 

FORTRAN SYNOPSIS 

integer *4 function ioctl (tildes, request, arg) 
integer*4 tildes, request, arg 

DESCRIPTION 

ioctl performs a variety of control functions on devices and STREAMS. For 
non-STREAMS files, the functions performed by this call are device-specific 
control functions. The request and optional third argument are passed to 
the file designated by fildes and are interpreted by the device driver. For a 
given device, the requests that are understood are documented in the section 
7 manual page for that device. This control is infrequently used on non- 
STREAMS devices, with the basic input/output functions performed through 
the read{2) and write(2) system calls. 

For STREAMS files, specific functions are performed by the ioctl call as 
described in streamio(l). 

Fildes is an open file descriptor that refers to a device. Request selects the 
control function to be performed and will depend on the device being 
addressed. The optional third argument represents additional information 
that is needed by this specific device to perform the requested function. 
The data type of the third argument depends upon the particular control 
request, but it is either an integer or a pointer to a device-specific data struc- 
ture. 

In addition to device-specific and STREAMS functions, generic functions 
are provided by more than one device driver, for example, the general ter- 
minal interface [see termio(7)]. 

ioctl will fail for any type of file if one or more of the following are true: 

[EACCES] Future error. 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a device driver that accepts 

control functions. 

[EINTR] A signal was caught during the ioctl system call. 

ioctl will also fail if the device driver detects an error. In this case, the error 
is passed through ioctl without change to the caller. A particular driver 
might not have all of the following error cases. Other requests to device 
drivers will fail if one or more of the following are true: 
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[EFAULT] Request requires a data transfer to or from a buffer 

pointed to by the third argument but some part of the 
buffer is outside the process's allocated space. 

[EINVAL] Request or the third argument is not valid for this device. 

[EIO] Some physical I/O error has occurred. 

[ENXIO] The request and the third argument are valid for this dev- 

ice driver, but the service requested can not be performed 
on this particular subdevice. 

STREAMS errors are described in streamio(l). 

SEE ALSO 

streamio(7), termio(7) in the System Administrator' s Reference Manual. 

DIAGNOSTICS 

Upon successful completion, the value returned depends upon the device 
control function, but must be a non-negative integer. Otherwise, a value of 
-1 is returned and err no is set to indicate the error. 
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NAME 

kill - send a signal to a process or a group of processes 
FORTRAN SYNOPSIS 

integer function kill (pid, sig) 

DESCRIPTION 

kill sends a signal to a process or a group of processes. The process or 
group of processes to which the signal is to be sent is specified by pid. The 
signal that is to be sent is specified by sig and is either one from the list 
given in signal(2) 9 or 0. If sig is (the null signal), error checking is per- 
formed but no signal is actually sent. This can be used to check the validity 
of pid. 

The real or effective user ID of the sending process must match the real, 
saved, or effective user ID of the receiving process, unless the effective 
user ID of the sending process is super-user. An exception to this is the sig- 
nal SIGCONT, which may be sent to any descendant, or any process in the 
same session (having the same session ID) as the current process. 

The processes with a process ID of and a process ID of 1 are special 
processes [see intro(2)] and will be referred to below as procO and prod , 
respectively. 

lipid is greater than zero, sig will be sent to the process whose process ID 
is equal io pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod 
whose process group ID is equal to the process group ID of the sender. 

If pid is -1 and the effective user ID of the sender is not super-user, sig will 
be sent to all processes excluding procO and prod whose real user ID is 
equal to the effective user ID of the sender. 

If pid is -1 and the effective user ID of the sender is super-user, sig will be 
sent to all processes excluding procO and prod . 

If pid is negative but not -1, sig will be sent to all processes whose process 
group ID is equal to the absolute value of pid. 

kill will fail and no signal will be sent if one or more of the following are 
true: 

[EINVAL] Sig is not a valid signal number. 

[EINVAL] Sig is SIGKILL and pid is 1 (proc 1). 

[ESRCH] No process can be found corresponding to that specified 

by pid. 
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[ESRCH] The process group was given as but the sending pro- 

cess does not have a process group. 

[EPERM] The user ID of the sending process is not super-user, and 

its real or effective user ID does not match the real, 
saved, or effective user ID of the receiving process. 

SEE ALSO 

exec(2), getpid(2), setpgrp(2), setsid(2), signal(2), sigset(2), sigaction(2), 
sigprocmask(2), sigvec(3B), sigblock(3B), sigsetmask(3B), killpg(3B). 
kill(l) in the User' s Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
~1 is returned and errno is set to indicate the error. 
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NAME 

link - link to a file 

FORTRAN SYNOPSIS 

integer function link (pathl, path2) 
character*^*) pathl, path2 

DESCRIPTION 

Pathl points to a path name naming an existing file. Path2 points to a path 
name naming the new directory entry to be created, link creates a new link 
(directory entry) for the existing file. 

link will fail and no link will be created if one or more of the following are 
true: 

[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permis- 

sion. 

[ENOENT] The file named by pathl does not exist. 

[EEXIST] The link named by pathl exists. 

[ENAMETOOLONG] 

The length of the pathl or path2 argument exceeds 
{PATH MAX}, or a pathname component is longer than 
{NAME _M AX) . 

[EPERM] The file named by pathl is a directory and the effective 

user ID is not super-user. 

[EXDEV] The link named by path! and the file named by pathl are 

on different logical devices (file systems). 
[ENOENT] Pathl points to a null path name. 

[EACCES] The requested link requires writing in a directory with a 

mode that denies write permission. 

[EROFS] The requested link requires writing in a directory on a 

read-only file system. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[EMLINK] The maximum number of links to a file would be 

exceeded. 
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SEE ALSO 

unlink(2). 



DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 

-1 is returned and err no is set to indicate the error. ^ 
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NAME 

Iseek - move read/write file pointer (System V and 4.3BSD) 
FORTRAN SYNOPSIS 

integer*4 function Iseek (fildes, offset, whence) 

integer*4 fildes, offset, whence 

DESCRIPTION 

Fildes is a file descriptor returned from a creat, open, dup, orfcntl system 
call. Iseek sets the file pointer associated with fildes as follows: 

If whence is SEEKSET (L_SET), the pointer is set to offset bytes. 

If whence is SEEK_CUR (LINCR), the pointer is set to its current 
location plus offset. 

If whence is SEEKEND (L_XTND), the pointer is set to the size of 
the file plus offset. 

Upon successful completion, the resulting pointer location, as measured in 
bytes from the beginning of the file, is returned. Note that if fildes is a 
remote file descriptor and offset is negative, Iseek will return the file pointer 
even if it is negative. 

Iseek allows the file offset to be set beyond the end of existing data in the 
file. If data is later written at that point, subsequent reads of the data in the 
gap return bytes with the value zero until data is actually written into the 
gap. 

Iseek will fail and the file pointer will remain unchanged if one or more of 
the following are true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe, socket, or fifo. 

[EINVAL and SIGS YS signal] 

Whence is not a proper value. 

[EINVAL] Fildes is not a remote file descriptor, and the resulting 

file pointer would be negative. 

Some devices are incapable of seeking. The value of the file pointer associ- 
ated with such a device is undefined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), open(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer indicating the file 
pointer value is returned. Otherwise, a value of -1 is returned and errno is 
set to indicate the error. 
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NAME 

mkdir - make a directory 

FORTRAN SYNOPSIS 

integer *4 function mkdir (path, mode) 
character * (*) path 
integer *4 mode 

DESCRIPTION 

The routine mkdir creates a new directory with the name path. The mode of 
the new directory is initialized from the mode. The protection part of the 
mode argument is modified by the process's mode mask [see umask(2)]. 

The directory's owner ID is set to the process's effective user ID. The 
directory's group ID is set to the process's effective group ID or the group 
ID of the directory in which the directory is being created. This is deter- 
mined as follows: 

If the underlying filesystem was mounted with the BSD file crea- 
tion semantics flag [see fstab(4)] or the SJSGID bit is set [see 
chmod(2)] on the parent directory, then the group ID of the new 
file is set to the group ID of the parent directory, otherwise it is set 
to the effective group ID of the calling process. 
The newly created directory is empty with the possible exception of entries 
for"." and"..". 

mkdir will fail and no directory will be created if one or more of the follow- 
ing are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[ENAMETOOLONG] The length of the path argument exceeds 
{PATHJ4AX}, or a pathname component is longer than 

{NAME _M AX} . 

[EACCES] Either a component of the path prefix denies search 

permission or write permission is denied on the parent 
directory of the directory to be created. 

[ENOENT] The path is longer than the maximum allowed. 

[EEXIST] The named file already exists. 

[EROFS] The path prefix resides on a read-only file system. f 

[EFAULT] Path points outside the allocated address space of the 

process. 
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The maximum number of links to the parent directory 
would exceed {LINKMAXJ . 

No space is available. 

An I/O error has occurred while accessing the file sys- 
tem. 

SEE ALSO 

mkdir(l), chmod(2), mknod(2), unlink(2), fstab(4). 
DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned, and errno is set to indicate the error. 
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NAME 

mknod - make a directory, or a special or ordinary file 

FORTRAN SYNOPSIS 

integer *4 function mknod (path, mode, dev) 
character * (■*) path 
integer *4 mode, dev 

DESCRIPTION 

mknod creates a new file named by the path name pointed to by path. The 
mode of the new file (including file type bits) is initialized from mode. The 
value of the file type bits which are permitted are: 

S JFIFO fifo special 
S JFCHR character special 
S IFBLK block special 
S JFREG ordinary file 

All other mode bits are interpreted as described in chown(2). 
The owner ID of the file is set to the effective user ID of the process. The 
group ID of the file is set to the effective group ID of the process or the 
group ID of the directory in which the file is being created. This is deter- 
mined as follows: 

If the underlying filesystem was mounted with the BSD file crea- 
tion semantics flag [see fstab(A)} or the S JSGID bit is set [see 
chmod(2)] on the parent directory, then the group ID of the new 
file is set to the group ID of the parent directory, otherwise it is set 
to the effective group ID of the calling process. 

Values of mode other than those above are undefined and should not be 
used. The low-order 9 bits of mode are modified by the process's file mode 
creation mask: all bits set in the process's file mode creation mask are 
cleared [see umask(2)l If mode indicates a block or character special file, 
dev is a configuration-dependent specification of a character or block I/O 
device. If mode does not indicate a block special or character special dev- 
ice, dev is ignored. 

mknod may be invoked only by the super-user for file types other than FIFO 
special. 

mknod will fail and the new file will not be created if one or more of the 
following are true: 
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[EPERM] The effective user ID of the process is not super-user. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EROFS] The directory in which the file is to be created is 

located on a read-only file system. 

[EEXIST] The named file exists. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[ENAMETOOLONG] The length of the path argument exceeds 
{PATH MAX}, or a pathname component is longer than 

{NAMEJ1AX}. 

[ENOSPC] No space is available. 

[EINVAL] If you create files of the type fifo special, character 

special, or block special on an NFS-mounted file sys- 
tem. 

SEE ALSO 

chmod(2), exec(2), mkdir(2), umask(2), fstab(4). 
mkdir(l) in the User's Reference Manual 

DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 



mount - mount a file system 



FORTRAN SYNOPSIS 

integer *4 function mount (spec, dir, [ mflag, fstyp, [ data, datalen ] ]) 
character * (*) spec, dir 
integer *4 mflag, fstyp 
integer *4 data, datalen 

DESCRIPTION 

mount attaches a file system to a directory. After a successful return, refer- 
ences to directory dir will refer to the root directory on the newly mounted 
file system. Dir is a pointer to a pathname of a existent directory. Its old 
contents are inaccessible while the filesystem is mounted. Spec and dir are 
pointers to path names. Fstyp is the file system type number. The sysfs(2) 
system call can be used to determine the file system type number. Note that 
if the MS_FSS flag bit of mflag is off, the file system type will default to the 
root file system type. Only if the bit is on mil fstyp be used to indicate the 
file system type. 

The low-order bit of mflag is used to control write permission on the 
mounted file system; if 1, writing is forbidden, otherwise writing is permit- 
ted according to individual file accessibility. 

mount may be invoked only by the super-user. It is intended for use only 
by the mountQM) utility. 

mount will fail if one or more of the following are true: 

[EPERM] The effective user ID is not super-user. 

[ENOENT] Any of the named files does not exist. 

[ENOTDIR] A component of a path prefix is not a directory. 

[ENOTBLK] Spec is not a block special device. 

[ENXIO] The device associated with spec does not exist. 

[ENOTDIR] Dir is not a directory. 

[EFAULT] Spec or dir points outside the allocated address space of 

the process. 

[EBUSY] Dir is currently mounted on, is someone's current work- 

ing directory, or is otherwise busy. 

[EBUSY] The device associated with spec is currently mounted. 

[EBUSY] There are no more mount table entries. 
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[EROFS] Spec is write protected and mflag requests write permis- 

sion. 

[ENOSPC] The file system state in the super-block is not FsOKAY 

and mflag requests write permission. 

[EINVAL] The super block has an invalid magic number or \hofstyp 

is invalid or mflag is not valid. 

SEE ALSO 

sysfs(2), umount(2), fs(4). 

mount(lM) in the System Administrator' s Reference Manual. 

DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned and err no is set to indicate the error. 
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NAME 

nice - change priority of a process 

FORTRAN SYNOPSIS 

integer *4 function nice (incr) 
integer *4 incr 

DESCRIPTION 

nice adds the value of incr to the nice value of the calling process. A 
process's nice value is a non-negative number for which a more positive 
value results in lower CPU priority. 

A maximum nice value of 39 and a minimum nice value of are imposed 
by the system. (The default nice value is 20.) Requests for values above or 
below these limits result in the nice value being set to the corresponding 
limit. 

[EPERM] nice will fail and not change the nice value if incr is 

negative or greater than 39 and the effective user ID of 
the calling process is not super-user. 

SEE ALSO 

exec(2), setpriority(2), schedctl(2). 

nice(l), csh(l), sh(l) in the User' s Reference Manual. 

DIAGNOSTICS 

Upon successful completion, nice returns the new nice value minus 20. 
Otherwise, a value of -1 is returned and err no is set to indicate the error. 

NOTES 

The csh(l) has a version of nice as a builtin command which alas, has 
slightly different syntax and semantics. 
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NAME 

open - open for reading or writing 

FORTRAN SYNOPSIS 

integer *4 function open (path, oflag, mode) 
character * (*) path 
integer *4 oflag, mode 

DESCRIPTION 

Path points to a path name naming a file, open opens a file descriptor for 
the named file and sets the file status flags according to the value of oflag. 
For non-STREAMS [see intro(2)] files, oflag values are constructed by or- 
ing flags from the following list (only one of the first three flags below may 
be used): 

ORDONLY Open for reading only. 

OJVRONLY Open for writing only. 

ORDWR Open for reading and writing. 

OJVOCTTY If set, and path identifies a terminal device, the open func- 
tion shall not cause the terminal device to become the con- 
trolling terminal for the process. 

OJNfDELAY This flag may affect subsequent reads and writes [see 
read{2) and write(2)]. 

When opening a FIFO with O.RDONLY or OJVRONLY set: 

IfO_NDELAYisset: 

An open for reading-only will return without 
delay. An open for writing-only will return an 
error if no process currently has the file open for 
reading. 

IfO_NDELAYisclear: 

An open for reading-only will block until a process 
opens the file for writing. An open for writing- 
only will block until a process opens the file for 
reading. 

When opening a file associated with a communication line: 

IfO_NDELAYisset: 

The open will return without waiting for carrier. 
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IfO_NDELAYisclear: 

The open will block until carrier is present. 

OJMONBLOCK 

This flag functions identically to O..NDELAY with regard to 
the open function. [See read(2) and write(2))]. 

0_APPEND If set, the file pointer will be set to the end of the file prior to 
each write. 

OSYNC When opening a regular file, this flag affects subsequent 

writes. If set, each write (2) will wait for both the file data 
and file status to be physically updated. 

0_CREAT If the file exists, this flag has no effect. Otherwise, the 
owner ID of the file is set to the effective user ID of the pro- 
cess, the group ID of the file is set to the effective group ID 
of the process or to the group ID of the directory in which 
the file is being created. This is determined as follows: 

If the underlying filesystem was mounted with the 
BSD file creation semantics flag [see fstab(4)] or 
the S JSGID bit is set [see chmod(2)] on the parent 
directory, then the group ID of the new file is set to 
the group ID of the parent directory, otherwise it is 
set to the effective group ID of the calling process. 

The low-order 12 bits of the file mode are set to the value of 
mode modified as follows [see creat(2)]: 

All bits set in the file mode creation mask of the 
process are cleared [see umask(2)]. 

The "sticky bit" of the mode is cleared [see 
chmod(2)l 

O TRUNC If the file exists, its length is truncated to and the mode 
and owner are unchanged. 

(XEXCL If 0_EXCL and 0_CREAT are set, open will fail if the file 

exists. 

When opening a STREAMS file, ofiag may be constructed from 0_NDELAY 
or-ed with either OJIDONLY, O.WRONLY or 0_RDWR. Other flag values 
are not applicable to STREAMS devices and have no effect on them. The 
value of O.NDELAY affects the operation of STREAMS drivers and certain 
system calls [see read{2\ getmsg(2) 1 putmsg(2) and write(2)]. For drivers, 
the implementation of O.NDELAY is device-specific. Each STREAMS dev- 
ice driver may treat this option differently. 
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Certain flag values can be set following open as described in fcntl(2). 

The file pointer used to mark the current position within the file is set to the 
beginning of the file. 

The new file descriptor is set to remain open across execveQ) system calls 
[see/c/tf/(2)]. 

There is a system enforced limit on the number of open file descriptors per 
process {OPEN MAX) , whose value is returned by the getdtahlesize(2) func- 
tion. 

The named file is opened unless one or more of the following are true: 

[EACCES] A component of the path prefix denies search permis- 

sion. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJAAX} . 

[ELOOP] Too many symbolic links were encountered in 

translating the pathname. 

[EACCES] oflag permission is denied for the named file. 

[EAGAIN] The file exists, mandatory file/record locking is set, 

and there are outstanding record locks on the file [see 
chmod (2)]. 

[EEXIST] O.CREAT and O.EXCL are set, and the named file 

exists. 

[EFAULT] Path points outside the allocated address space of the 

process. 

[EINTR] A signal was caught during the open system call. 

[EIO] A hangup or error occurred during a STREAMS open . 

[EISDIR] The named file is a directory and oflag is write or 

read/write. 

[EMFILE] The system imposed limit for open file descriptors per 

process {OPEN MAX} has already been reached. 

[ENFILE] The system file table has exceeded {NFILEMAX} con- 

currently open files. 

[ENOENT] 0_CREAT is not set and the named file does not exist. 

[ENOMEM] The system is unable to allocate a send descriptor. 
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[ENOSPC] O.CREAT and O^EXCL are set, and the file system is 

out of inodes. 

[ENOSR] Unable to allocate a stream. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] The named file is a character special or block special 

file, and the device associated with this special file 
does not exist. 

[ENXIO] 0_NDELAY is set, the named file is a FIFO, 

OJVRONLY is set, and no process has the file open for 
reading. 

[ENXIO] A STREAMS module or driver open routine failed. 

[EROFS] The named file resides on a read-only file system and 

oflag is write or read/write. 

[ETXTBSY] The file is a pure procedure (shared text) file that is 

being executed and oflag is write or read/write. 

[EOPNOTSUPP] An attempt was made to open a socket (not currently 
supported). 

SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcnd(2), getdtablesize(2), intro(2), 
lseek(2), read(2), getmsg(2), putmsg(2), umask(2), write(2). 

DIAGNOSTICS 

Upon successful completion, the file descriptor is returned. Otherwise, a 
value of -1 is returned and err no is set to indicate the error. 
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NAME 

pause - suspend process until signal 
FORTRAN SYNOPSIS 

integer *4 function pause() 

DESCRIPTION 

pause suspends the calling process until it receives a signal. The signal 
must be one that is not currently set to be ignored by the calling process. 

If the signal causes termination of the calling process, pause will not return. 

If the signal is caught by the calling process and control is returned from 
the signal-catching function [see signal(2)], the calling process resumes 
execution from the point of suspension; with a return value of -1 from 
pause and errno set to EINTR. 

SEE ALSO 

alarm(2), kill(2), signal(2), sigpause(2), wait(2), sigaction(2), sigpend- 
ing(2), sigprocmask(2), sigsuspend(2), sigvec(3B), signal(3B), 
sigblock(3B), sigpause(3B), sigsetmask(3B). 
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NAME 

pipe - create an interprocess channel 

FORTRAN SYNOPSIS 

integer *4 function pipe (fildes) 
integer *4 fildes (2) 

DESCRIPTION 

pipe creates an I/O mechanism called a pipe and returns two file descrip- 
tors, yiMe,y[0] and fildes[ll Fildes[0] is opened for reading mdfildes[l] is 
opened for writing. 

Up to PIPE_BUF (defined in limits.h) are guaranteed to be written atomi- 
cally. Up to PIPEJV1AX (defined in limits.h) bytes of data are buffered by 
the pipe before the writing process is blocked. A read only file descriptor 
filde$[0] accesses the data written to fildes[l] on a first-in-first-out (FIFO) 
basis. 

pipe will fail if: 

[EMFILE] more than {OPENMAXJ-2 file descriptors are currently 

open. 

[ENFILE] The system file table has exceeded {NFILEJ4AX} con- 

currently open files. 

SEE ALSO 

read(2), write(2). 

sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

plock - lock process, text, or data in memory 

FORTRAN SYNOPSIS 

integer *4 function plock (op) 
integer *4 op 

DESCRIPTION 

plock allows the calling process to lock its text segment (text lock), its data 
and stack segments (data lock), or its text, data, and stack segments (process 
lock) into memory. Locked segments are immune to all routine swapping. 
plock also allows these segments to be unlocked. The effective user ID of 
the calling process must be super-user to use this call. Op specifies the fol- 
lowing: 

lock text and data segments into memory (process 
lock) 



PROCLOCK- 

TXTLOCK- 
DATLOCK- 
UNLOCK- 



lock text segment into memory (text lock) 

lock data and stack segments into memory (data lock) 

remove locks 

plock will fail and not perform the requested operation if one or more of the 
following are true: 

[EPERM] The effective user ID of the calling process is not super- 

user. 

[EINVAL] Op is equal to PROCLOCK and a process lock, a text 

lock, or a data lock already exists on the calling process. 

[EINVAL] Op is equal to TXTLOCK and a text lock or a process 

lock already exists on the calling process. 

[EINVAL] Op is equal to DATLOCK and a data lock or a process 

lock already exists on the calling process. 

[EINVAL] Op is equal to UNLOCK and no type of lock exists on the 

calling process. 

[EAGAIN] There was insufficient lockable memory to lock the 

requested segment. This may occur even though the 
amount requested was less than the system-imposed 
maximum number of locked pages. 

[ENOMEM] The caller was not super-user and the number of pages to 

be locked exceeded the per process limit {PLOCKMAX} . 
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[ENOMEM] The total number of pages locked by the caller would 

exceed the maximum resident size for the process [see 
setrlirnit(2)]. 

SEE ALSO 

intro(2), exec(2), exit(2), getrlimit(2), mpin(2), plock(2), shmctl(2), 
ulimit(2). 

WARNING 

If a locked data segment is grown, the newly-allocated pages are not locked 
into memory. 

DIAGNOSTICS 

Upon successful completion, a value of is returned to the calling process. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 

BUGS 

Shared library text and data segments and mapped files are not currently 
affected by calls to plock. 
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NAME 

prctl - operations on a process 

FORTRAN SYNOPSIS 

integer*4 prctl (option, [ value, [ value2]]) 
integer*4 option, value, value2 

DESCRIPTION 

prctl provides information about processes and the ability to control certain 
of their attributes. Option specifies one of the following actions: 

PRJVf AXPROCS returns the system imposed limit on the 

number of processes per user. 

PRJVfAXPPROCS returns the maximum number of 

processes the system is willing to run in 
parallel. 



PR ISBLOCKED 



PR SETSTACKSIZE 



PR GETSTACKSIZE 



PR UNBLKONEXEC 



returns 1 if the specified process is 
currently blocked, value specifies the 
pid. Since other processes could have 
subsequently unblocked the subject pro- 
cess, the result should be considered as 
a snapshot only. 

sets the maximum stack size for the 
current process. This affects future 
stack growths and forks only. The new 
value, suitably rounded, is returned. 
The value is expressed in terms of 
bytes. This option and the 
RLIMITJSTACK option of setrlimit{2) 
act on the same value. 

returns the current process's maximum 
stack size in bytes. This size is an 
upper limit on the size of the current 
process's stack. 

sets a flag so that when the calling pro- 
cess subsequently calls exec(2), the pro- 
cess whose pid is specified by value is 
unblocked. This can be used in con- 
junction with the PRBLOCK option of 
sproc{2) to provide race- free process 
creation. 
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PR SETEXITSIG 



controls whether all members of a share 
group will be signaled if any one of 
them terminates. If value is 0, then nor- 
mal IRIX process termination rules 
apply, namely that the parent is sent a 
SIGCLD upon death of child, but no 
indication of death of parent is given. If 
value is a valid signal number [see sig- 
nal(2)] then if any member of a share 
group terminates, that signal is sent to 
ALL surviving members of the share 
group. 



PR RESIDENT 



PR ATTACHADDR 



makes the process immune to process 
swapout. 

attaches the virtual segment containing 
the address value2 in the process whose 
pid is value to the calling process. Both 
processes must be members of the same 
share group. The address of where the 
virtual segment was attached is 
returned. This address has the same 
logical offset into the virtual space as 
the passed in address. 

prctl will fail if one or more of the following are true: 

[EINVAL] option is not valid. 

[ESRCH] The value passed with the PRJSBLOCKED or 

PRJJNBLKONEXEC option doesn't match the pid of 
any process. 

[EINVAL] The value given for the new maximum stack size is 

negative or exceeds the maximum process size allowed. 

[EINVAL] The value given for the PR^SETEXITSIG option is not a 

valid signal number. 

[EINVAL] The calling process already has specified a process (or 

the specified process is the caller itself) to be unblocked 
on exec via the PRJJNBLKONEXEC option. 

[EPERM] The caller does not have permission to unblock the pro- 

cess specified by the value passed for the 
PR UNBLKONEXEC option. 
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SEE ALSO 

blockproc(2), signal(2), setrlimit(2), sproc(2). 

DIAGNOSTICS 

Upon successful completion, prctl returns the requested information. Oth- 
erwise, a value of -1 is returned to the calling process, and errno is set to 
indicate the error. 
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NAME 

profil - execution time profile 

FORTRAN SYNOPSIS 

integer *4 function profil (buff, buffsiz, offset, scale) 

integer *2 (*) buff 

integer *4 bufsiz, offset, scale 

DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. 
After this call, the user's program counter (pc) is examined each clock tick 
(10 milliseconds); offset is subtracted from it, and the result multiplied by 
scale. If the resulting number corresponds to a word inside buff, that word 
is incremented. 

The scale is interpreted as an unsigned, fixed-point fraction with 16 bits of 
fraction: 0x10000 gives a 1-1 mapping of pc's to words in buff; 0x8000 
maps each pair of instruction words together. 

Since each bucket is only 16 bits, it is concievable for it to overflow. No 
indication that this has occurred is given. 

Profiling is turned off by giving a scale of or 1. It is rendered ineffective 
by giving a bufsiz of 0. Profiling is turned off when an execve is executed, 
but remains on in child and parent both after a fork or sproc. Profiling is s 
turned off if an update in buff would cause a memory fault. I 

SEE ALSO 

fork(2), sproc(2), monitor(3X). 

DIAGNOSTICS 

A 0, indicating success, is always returned. 



( 
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NAME 

ptrace - process trace 
FORTRAN SYNOPSIS 

integer *4 function ptrace (request, pid, addr, data) 

integer *4 request, pid, addr, data 

DESCRIPTION 

Ptrace provides a way for a process to control the execution of another pro- 
cess and to examine and change that process's core image. Ptrace is used 
primarily to implement breakpoint debugging. 

There are four arguments whose interpretation depends on a request argu- 
ment. Generally, pid is the process ID of the traced process. A process 
being traced behaves normally until it encounters some signal, whether 
internally generated (for example, "illegal instruction")) or externally gen- 
erated (for example, ' 'interrupt' '). See signal(2) for the list. 

When the traced process encounters a signal, it enters a stopped state. The 
process tracing it is notified by waif (2). If the the traced process stops with 
a SIGTRAP, the process might have stopped for many reasons. Two status 
words, which are addressable as registers, in the traced process's uarea 
qualify SIGTRAPs: TRAPCAUSE, which contains the cause of the trap, 
and TRAPINFO, which contains extra information about the trap. 

When the traced process is in the stopped state, its core image can be exam- 
ined and modified using ptrace. Another ptrace request can cause the 
traced process either to terminate or to continue, possibly ignoring the sig- 
nal. 

The value of the request argument determines the precise action of the call: 

This request is the only one that can be used by a child process. 
Request can declare that the child process is to be traced by its 
parent. All other arguments are ignored. Peculiar results happen when 
the parent does not expect to trace the child. 

1,2 The word in the traced process's address space at addr is returned. If I 
and D space are separated (for example, historically on a PDP-11), 
Request 1 specifies I space and Request 2 specifies D space. Addr 
must be 4-byte aligned. The traced process must be stopped. The 
input data is ignored. 

3 The word of the system's per-process data area that corresponds to 
addr is returned. Addr is a constant defined in ptrace.h. This space 
contains the registers and other information about the process. The 
constants correspond to fields in the system's user structure. 
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4,5 The specified data is written at the word in the process's address space 
corresponds to addr. Addr must be 4-byte aligned. Upon successful 
completion, the value written into the address space of the child is 
returned to the parent. If I and D space are separated, Request 4 
specifies I space and Request 5 specifies D space. Attempts to write in 
pure procedure fail when another process is executing the same file. | 

6 The process's system data is written as it is read with Request 3. Only 
a few locations can be written this way: the general registers, the float- 
ing point status and registers, and certain bits of the processor status 
word. The old value at the address is returned. 

7 The data argument is taken as a signal number and the traced process's 
execution continues at location addr as if it had incurred that signal. 
The signal number can be 0, indicating the signal that caused the stop 
should be ignored, or the signal can be the value fetched from the 
process's image, indicating what signal caused the stop. If addr is (int 
*) 1 , execution continues from where it stopped. 

8 The traced process terminates. The addr argument is ignored and the 
data argument is the signal specified in Request 7. 

9 Execution continues as in Request 7; however, as soon as possible 
after execution of at least one instruction, execution stops again. The 
signal number from the stop is SIGTRAP. TRAPCAUSE contains / 
CAUSESINGLE. This part of ptrace is used to implement break- V 
points. The addr and data arguments are defined in Request 7. 

Requests 20-29 have not been fully defined or implemented. 

20 This request is the same as Request 0, except it is executed by the trac- 
ing process and the pid field is non-zero. That pid's process pid stops 
execution. On a signal, it becomes a traced process that returns control 
to the tracing process rather than to the parent. The tracing process 
must have the same user-id (uid) as the traced process. 

21,22 

These requests return MAXREG general registers or MAXFREG 
floating registers, respectively. Their values are copied to the locations 
starting at the address in the tracing process specified by the addr argu- 
ment. 



24,25 

These requests are the same as Requests 20 and 21, except that they 
write the registers instead of reading them. 



( 



April 1990 



, 2 - Version 3.0 



PTRACE(2) Silicon Graphics PTRACE(2) 

26 This request specifies a watchpoint in the data or stack segment of the 
traced process. If any byte address (starting at the addr argument and 
continuing for the number of bytes specified by the data argument) is 
accessed in an instruction, the traced process stops execution with a 
SIGTRAP. TRAPCAUSE contains CAUSEWATCH; TRAPINFO 
contains the address causing the trap. Ptrace returns a wid (watch- 
point identifier). MAXWIDS specifies the maximum number of 
watchpoints per process. 

27 This request's data argument specifies a wid to delete. 

28 This request turns off tracing for the traced process that has the 
specified pid. 

29 This request returns an open file descriptor for the file attached to pid. 
This is useful for accessing the symbol table of an execed process. 

These calls (except for Requests and 20) can be used only when the sub- 
ject process has terminated. The wait call determines when a process ter- 
minates. Then, the "termination" status returned by wait has the value 
0177 to show stoppage rather than termination. If multiple processes are 
being traced, wait can be called multiple times and returns the status for the 
next stopped child, terminated child, or traced process. 

To prevent fraud, ptrace inhibits the set-user-id and set-group-id facilities 
on later execve{2) calls. If a traced process calls execve, the process ter- 
minates before executing the first instruction of the new image showing sig- 
nal SIGTRAP. TOAPCAUSE contains CAUSEEXEC; TRAPINFO does 
not contain anything interesting. If a traced process execs again, the same 
thing happens. 

If a traced process forks, both parent and child are traced, and the break- 
points from the parent are copied into the child. At the time of the fork, the 
child stops with a SIGTRAP. The tracing process can end the trace, if 
desired. TRAPCAUSE contains CAUSEFORK; TRAPINFO contains the 
its parent's pid. 

RETURN VALUE 

If the call succeeds, a value is returned. If the call fails, then a -1 is 

returned and the global variable errno is set to indicate the error. 
ERRORS 

[EINVAL] The request code is invalid. 

[EINVAL] The specified process does not exist. 

[EINVAL] The given signal number is invalid. 
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[EFAULT] The specified address is out of bounds. 

[EPERM] The specified process cannot be traced. 

SEE ALSO 

wait(2), sigvec(2). 

BUGS 

There is file system called /debug where each "file" is actually an active 
process. The process' file name is /debug/processid where processid is the 
process number. open(2\ read{2\ etc can be used to acess the (running) 
process. Use/cnf/(2) to control the process. See <$yslfsfdbfcntl.h> for a list 
of the control functions available. The /debug facility solves the problems 
with ptrace mentioned below. 

Ptrace is unique and arcane; it should be replaced with a special file that 
can be opened, read, and written. The control functions could be imple- 
mented with ioctl{2) calls on this file. This would be easier to understand 
and have much higher performance. 

The Request call should specify signals that are to be treated normally and 
should not cause a termination. Then, programs with simulated floating 
point (which use "illegal instruction" signals at a high rate) could be 
efficiently debugged. 

The error indication -1 is a legitimate function value errno. See intro{2) to 
disambiguate. 

It should be possible to stop a process on occurrence of a system call. In 
this way, a completely controlled environment could be provided. 
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NAME 

read - read from file 

FORTRAN SYNOPSIS 

integer *4 function read (tildes, buf, nbyte) 
integer *4 fildes 
character * (*) buf 
integer *4 byte 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat(2), open(2), dup(2), 
fcntl(2), socket (2), socketpair(2), or pipe (2) system call. 

read attempts to read nbyte bytes from the file associated with fildes into 
the buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given 
by the file pointer associated with fildes. Upon return from read, the file 
pointer is incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position,. 
The value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read 
and placed in the buffer; this number may be less than nbyte if the file is 
associated with a communication line [see ioctl(2) and termio(l)] t or a 
socket [see socket -(2)], or if the number of bytes left in the file is less than 
nbyte bytes. A value of is returned when an end-of-file has been reached. 

A read from a STREAMS [see intro(2)] file can operate in three different 
modes: "byte-stream" mode, "message-nondiscard" mode, and "message- 
discard" mode. The default is byte-stream mode. This can be changed 
using the I_SRDOPT ioctl request [see streamio(7)] 9 and can be tested with 
the L.GRDOPT ioctl. In byte-stream mode, read will retrieve data from the 
stream until it has retrieved nbyte bytes, or until there is no more data to be 
retrieved. Byte-stream mode ignores message boundaries. 

In STREAMS message-nondiscard mode, read retrieves data until it has read 
nbyte bytes, or until it reaches a message boundary. If the read does not 
retrieve all the data in a message, the remaining data are replaced on the 
stream, and can be retrieved by the next read or getmsg(2) call. Message- 
discard mode also retrieves data until it has retrieved nbyte bytes, or it 
reaches a message boundary. However, unread data remaining in a mes- 
sage after the read returns are discarded, and are not available for a subse- 
quent read or getmsg. 
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When attempting to read from a regular file with mandatory file/record 
locking set [see chmod(2% and there is a blocking (i.e. owned by another 
process) write lock on the segment of the file to be read: 

If O.NDELAY or O.NONBLOCK is set, the read will return a -1 
and set errno to EAGAIN. 

If Q_NDELAY and O.NONBLOCK are clear, the read will sleep 
until the blocking record lock is removed. 

When attempting to read from an empty pipe (or FIFO): 

If O.NDELAY is set, the read will return a 0. 

If O.NONBLOCK is set, the read will return a -1 and set errno to 

EAGAIN. 

If O.NDELAY and O.NONBLOCK are clear, the read will block 
until data is written to the file or the file is no longer open for writ- 
ing. 

When attempting to read a file associated with a tty that has no data 

currently available: 

If O.NDELAY is set, the read will return a 0. 

If O.NONBLOCK is set, the read will return a -1 and set errno to 
EAGAIN. 

If O.NDELAY and O.NONBLOCK are clear, the read will block 
until data becomes available. 

When attempting to read a file associated with a stream that has no data 
currently available: 

If O.NDELAY or O.NONBLOCK is set, the read will return a -1 

and set errno to EAGAIN. 

If O.NDELAY and O.NONBLOCK are clear, the read will block 
until data becomes available. 

Due to the different semantics of O.NDELAY and O.NONBLOCK in two of 
the above 4 cases, these flags must not be used simultaneously. 

When reading from a STREAMS file, handling of zero-byte messages is 
determined by the current read mode setting. In byte-stream mode, read 
accepts data until it has read nhyte bytes, or until there is no more data to 
read, or until a zero-byte message block is encountered, read then returns 
the number of bytes read, and places the zero-byte message back on the 
stream to be retrieved by the next read or gelmsg. In the two other modes, 
a zero-byte message returns a value of and the message is removed from 
the stream. When a zero-byte message is read as the first message on a 
stream, a value of is returned regardless of the read mode. 
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A read from a STREAMS file can only process data messages. It cannot 
process any type of protocol message and will fail if a protocol message is 
encountered at the stream head. 

read will fail if one or more of the following are true: 

[EAGAIN] Mandatory file/record locking was set, O.NDELAY was 

set, and there was a blocking record lock. 

[ENOMEM] Insufficient amount of system virtual memory is avail- 

able with which to map the user pages when reading via 
raw 10. 

[EAGAIN] No message waiting to be read on a stream and 

0_NDELAY flag set. 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EBADMSG] Message waiting to be read on a stream is not a data 

message. 

[EDEADLK] The read was going to go to sleep and cause a deadlock 

situation to occur. 

[EFAULT] Buf points outside the allocated address space. 

[EDMTR] A signal was caught during the read system call. 

[EINVAL] Attempted to read from a stream linked to a multiplexor. 

[ENOLCK] The system record lock table was full, so the read could 

not go to sleep until the blocking record lock was 
removed. 

A read from a STREAMS file will also fail if an error message is received at 
the stream head. In this case, errno is set to the value returned in the error 
message. If a hangup occurs on the stream being read, read will continue 
to operate normally until the stream head read queue is empty. Thereafter, 
it will return 0. 

SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2), intro(2), open(2), pipe(2), getmsg(2), 
socket(2). 

streamio(7), termio(7) in the System Administrator' s Reference Manual. 
DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating 
the number of bytes actually read. Otherwise, a -1 is returned and errno is 
set to indicate the error. 
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NAME 

readlink - read value of a symbolic link 

FORTRAN SYNOPSIS 

integer *4 function readlink (path, buf, bufsize) 

character * (*) path, buf . 

integer *4 bufsize ■ 

DESCRIPTION 

Readlink places the contents of the symbolic link path in the buffer buf 
which has size bufsiz. The contents of the link are not null terminated when 
returned. 

RETURN VALUE 

The call returns the count of characters placed in the buffer if it succeeds, or 
a -1 if an error occurs, placing the error code in the global variable errno. 

ERRORS 

Readlink will fail and the file mode will be unchanged if: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[ENXIO] The named file is not a symbolic link. 

[EACCES] Search permission is denied on a component of the path 

prefix. 
[EFAULT] Buf extends outside the process's allocated address 

space. 
[ELOOP] Too many symbolic links were encountered in translating 

the pathname. 

SEE ALSO 

stat(2), symlink(2) 
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NAME 

rmdir - remove a directory 

FORTRAN SYNOPSIS 

integer *4 function rmdir (path) 
character * (*) path 

DESCRIPTION 

rmdir removes the directory named by the path name pointed to by path. 
The directory must not have any entries other than "." and "..". 

The named directory is removed unless one or more of the following are 
true: 

[EINVAL] The current directory may not be removed. 

[EINVAL] The "." entry of a directory may not be removed. 

[EEXIST] The directory contains entries other than those for "." 

and "..-. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for a component of the 

path prefix. 

[EACCES] Write permission is denied on the directory containing 

the directory to be removed. 

[EACCES] The parent directory of the directory to be removed 

has the sticky bit set and 
the parent directory is not owned by the user and 
the directory to be removed is not owned by the user 
and 

the directory to be removed is not writable by the user 
and 
the user is not superuser. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJiAXJ . 

[EBUSY] The directory to be removed is the mount point for a 

mounted file system. 

[EROFS] The directory entry to be removed is part of a read- 

only file system. 

[EFAULT] Path points outside the process's allocated address 

space. 
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[EIO] An I/O error occurred while accessing the file system. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 

SEE ALSO 

mkdir(2). 

rmdir(l), rm(l), and mkdir(l) in the U ser 1 s Reference Manual 
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NAME 

send, sendto, sendmsg - send a message from a socket 
FORTRAN SYNOPSIS 

integer *4 function send (s, msg, len, flags) 

integer *4 s 

character * (*) msg 

integer *4 len, flags 

DESCRIPTION 

Send, sendto, and sendmsg are used to transmit a message to another 
socket. Send may be used only when the socket is in a connected state, 
while sendto and sendmsg may be used at any time. 

The address of the target is given by to with tolen specifying its size. The 
length of the message is given by len. If the message is too long to pass 
atomically through the underlying protocol, then the error EMSGSIZE is 
returned, and the message is not transmitted. 

No indication of failure to deliver is implicit in a send. Return values of -1 
indicate some locally detected errors. 

If no messages space is available at the socket to hold the message to be 
transmitted, then send normally blocks, unless the socket has been placed in 
non-blocking I/O mode. The select(2) call may be used to determine when 
it is possible to send more data. 

The flags parameter may include one or more of the following: 

#define MSG_OOB Oxl /* process out-of-band data */ 

#define MSG_DONTROUTE 0x4 /* bypass routing, 

use direct interface */ 

The flag MSG_OOB is used to send << out-of-band , ' data on sockets that 
support this notion (e.g., SOCK_STREAM); the underlying protocol must 
also support * 'out-of-band' ' data. MSG_DONTROUTE is usually used 
only by diagnostic or routing programs. 

See recv(2) for a description of the msghdr structure. 
RETURN VALUE 

The call returns the number of characters sent, or -1 if an error occurred. 
ERRORS 

[EBADF] An invalid descriptor was specified. 

[ENOTSOCK] The argument s is not a socket. 
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An invalid user space address was specified for a 
parameter. 

The socket requires that message be sent atomi- 
cally, and the size of the message to be sent made 
this impossible. 

The socket is marked non-blocking and the 
requested operation would block. 

The system was unable to allocate an internal 
buffer. The operation may succeed when buffers 
become available. 

The output queue for a network interface was full. 
This generally indicates that the interface has 
stopped sending, but may be caused by transient 
congestion. 

SEE ALSO 

fcntl(2), recv(2), select(2), getsockopt(2), socket(2), write(2) 



[EFAULT] 



[EMSGSIZE] 



[EWOULDBLOCK] 



[ENOBUFS] 
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NAME 

setpgrp, BSDsetpgrp - set process group ID (System V and 4.3BSD) 

FORTRAN SYNOPSIS 

integer *4 function setpgrp () 

DESCRIPTION 

The System V version of setpgrp sets the process group ID of the calling 
process to the process ID of the calling process and returns the new process 
group ID. 

The BSD version of setpgrp set the process group of the specified process 
pid to the specified pgrp. If pid is zero, then the call applies to the current 
process. 

If the invoker is not the super-user, then the affected process must have the 
same effective user-id as the invoker or be a descendant of the invoking 
process. 

ERRORS: BSD VERSION ONLY 

setpgrp and BSDsetpgrp will fail and the process group will not be altered if 
one of the following occur: 

[ESRCH] The requested process does not exist. 

[EPERM] The effective user ID of the requested process is different 

from that of the caller and the process is not a descendent 
of the calling process. 

SEE ALSO 

exec(2), fork(2), getpgrp(2), getpid(2), intro(2), kill(2), setpgid(2), sig- 
nal(2). 

DIAGNOSTICS 

The System V version of setpgrp returns the value of the new process 
group ID with no possibility of error. The BSD version also returns the new 
process group ID if the operation was successful. If the request failed, -1 is 
returned and the global variable errno indicates the reason. 
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NAME 

setuid, setgid - set user and group IDs 

FORTRAN SYNOPSIS 

integer *4 function setuid (uid) 
integer *4 uid 

integer *4 function setgid (gid) 
integer *4 gid 

DESCRIPTION 

setuid (setgid) is used to set the real user (group) ID and effective user 
(group) ID of the calling process. 

If the effective user ID of the calling process is super-user, the real user 
(group) ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real 

user (group) ID is equal to uid (gid), the effective user (group) ID is set to 

uid (gid). 

If the effective user ID of the calling process is not super-user, but the saved 

set-user (group) ID from exec(2) is equal to uid (gid), the effective user 

(group) ID is set to uid (gid). 

setuid or setgid will fail if one or more of the following are true: 

[EPERM] setuid (setgid) will fail if the real user (group) ID of the 

calling process is not equal to uid (gid) and its effective 
user ID is not super-user. 

[EINVAL] The uid (gid) is out of range. 

SEE ALSO 

getuid(2), intro(2). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

sginap - timed sleep and processor yield function 

FORTRAN SYNOPSIS 

subroutine sginap (ticks) 
integer *4 ticks 

DESCRIPTION 

The sginap system call provides two functions. With an argument of 0, it 
yields the processor to any higher or equal priority processes immediately, 
thus potentially allowing another process to run. Note that because nor- 
mally the user has no direct control over the exact priority of a given pro- 
cess, this does not guarantee that another process will run. 

With an argument which is non-zero, sginap will suspend the process for 
ticks clock ticks. The length of a clock tick is defined by CLKTCK in the 
include file <limits.h>. This is the same for all IRIS-4D products. 

SEE ALSO 

sleep(3), alarm(2), pause(2), schedctl(2), setitimer(2). 
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NAME 

shmop: shmat, shmdt - shared memory operations 

FORTRAN SYNOPSIS 

integer *4 function shmdt (shmaddr) 
character * (*) shmaddr 

DESCRIPTION 

shmat attaches the shared memory segment associated with the shared 
memory identifier specified by shmid to the data segment of the calling pro- 
cess. The segment is attached at the address specified by one of the follow- 
ing criteria: 

If shmaddr is equal to zero, the segment is attached at the first 

available address as selected by the system. 

If shmaddr is not equal to zero and (shmflg & SHMJfcND) is 
* 'true' ' , the segment is attached at the address given by (shmaddr - 
(shmaddr modulus SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & SHM_RND) is 
"false", the segment is attached at the address given by shmaddr. 

shmdt detaches from the calling process's data segment the shared memory 
segment located at the address specified by shmaddr. 

The segment is attached for reading if (shmflg & SHM_RDONLY) is * 'true' * i 
{READ} , otherwise it is attached for reading and writing {READ/WRITE} . ^ 

shmat will fail and not attach the shared memory segment if one or more of 

the following are true: 

[EINVAL] Shmid is not a valid shared memory identifier. 

[EACCES] Operation permission is denied to the calling process [see 

intro(2)l 

[ENOMEM] The available virtual space of the caller (either total size 

{PROCSI2EJ4AX} or a large enough gap between other 
previously allocated virtual spaces) cannot accommodate 
the shared memory segment. 

[EINVAL] Shmaddr is not equal to zero, and the value of (shmaddr 

- (shmaddr modulus SHMLBA)) is an illegal address. 

[EINVAL] Shmaddr is not equal to zero, (shmflg & SHMJIND) is 

"false", and the value of shmaddr is an illegal address. / 
Attach addresses must be a multiple of SHMLBA [see V 
<sys/shm.h>]. 
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[EMFILE] The number of shared memory segments attached to the 

calling process would exceed the system-imposed limit 
{SHMAT_MAX} [see intro(2)l 

shmdt will fail and not detach the shared memory segment if one or more of 
the following are true: 

[EBUSY] The shared memory segment is in use by another 

member of the calling process's share group [see 
sproc(2)]. 

[EINVAL] Shmaddr is not the start address of a shared memory seg- 

ment. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2), sproc(2). 

DIAGNOSTICS 

Upon successful completion, the return value is as follows: 

shmat returns the data segment start address of the attached shared 
memory segment. 

shmdt returns a value of 0. 
Otherwise, a value of -1 is returned and errno is set to indicate the error. 
NOTES 

The user must explicitly remove shared memory segments after the last 
reference to them has been removed. 
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NAME 



signal - software signal facilities (System V) 



FORTRAN SYNOPSIS 

integer function signal (sig, func, flag) 
integer sig, func, flag 
external func 

DESCRIPTION 

signal allows the calling process to choose one of three ways in which it is 
possible to handle the receipt of a specific signal. Sig specifies the signal 
mdfunc specifies the choice. 

FORTRAN interface routine signal takes an extra argument flag, if flag is a 
negative value func must be an external FORTRAN procedure name. Other- 
wise, func is ignored and flag can contain SIGJDFL, SIGJGN, or the 
address of a C signal-handling routine. In this case, ./tog will be passed to 
the system call signal as func. flag may be the value returned from a previ- 
ous call to signal and, thus, can be used to restore a previous action 
definition. Note that flag can only be an integer variable containing the 
address of a C function and not the C function itself. Sig is the signal to be 
caught, and must be in the range 

(0<sig<NSIG). 
Sig can be assigned any one of the following except SIGKILL or SIGSTOP: 



SIGHUP 


01 


hangup 


SIGINT 


02 


interrupt 


SIGQUTT 


03 [1] 


quit 


SIGILL 


04 [1] 


illegal instruction (not reset when caught) 


SIGTRAP 


05 [l][5] 


trace trap (not reset when caught) 


SIGABRT 


06 ll] 


abort 


SIGEMT 


0y[l][4] 


EMT instruction 


SIGFPE 


08 [1] 


floating point exception 


SIGKILL 


09 


kill (cannot be caught or ignored) 


SIGBUS 


10 [l] 


bus error 


SIGSEGV 


n [U 


segmentation violation 


SIGSYS 


12 [l] 


bad argument to system call 


SIGPIPE 


13 


write on a pipe with no one to read it 


SIGALRM 


14 


alarm clock 


SIGTERM 


15 


software termination signal 


SIGUSR1 


16 


user-defined signal 1 


SIGUSR2 


17 


user-defined signal 2 


SIGCLD 


18 [2] 


death of a child 



( 



( 



( 
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SIGPWR 

SIGSTOP 

SIGTSTP 

SIGPOLL 

SIGIO 

SIGURG 

SIGWINCH 

SIGVTALRM 

SIGPROF 

SIGCONT 

SIGTTIN 

SIGTTOU 

SIGXCPU 

SIGXFSZ 



19 [2] 

20 [6] 
21 [6] 

22 [3] 

23 [2] 
24 [2] 

25 [2] 

26 

27 

28 [6] 

29 [6] 

30 [6] 

31 

32 



power fail (not reset when caught) 

stop (cannot be caught or ignored) 

stop signal generated from keyboard 

selectable event pending 

input/output possible 

urgent condition on 10 channel 

window size changes 

virtual time alarm 

profiling alarm 

continue after stop (cannot be ignored) 

background read from control terminal 

background write to control terminal 

cpu time limit exceeded [see setrlimit(2)] 

file size limit exceeded [see setrlimit{2)] 



Func is assigned one of three values: SIGJ)FL or SIGJGN, which are 
macros (defined in <syslsignal.h>) that expand to constant expressions, or 
a function address. 

The actions prescribed by its value are as follows: 

SIGDFL - terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be 
terminated with all of the consequences outlined in exit(2). See 
SIGNAL NOTES [1] below. 

SIG_IGN- ignore signal 

The signal sig is to be ignored. 

Note: the signals SIGKILL, SIGSTOP and SIGCONT cannot be 
ignored. 

function address - catch signal 

Upon receipt of the signal sig, the receiving process is to exe- 
cute the signal-catching function whose address is specified via 
this parameter. The function will be invoked as follows: 

handler (int sig, int code, struct sigcontext *sc); 

Where handler is the specified function-name, code is valid 
only in the following cases: 

Condition Signal Code 



User breakpoint 
User breakpoint 
Integer overflow 
Divide by zero 
Multiply overflow 



SIGTRAP 
SIGTRAP 
SIGTRAP 
SIGTRAP 
SIGTRAP 



BRKUSERBP 

BRK_SSTEPBP 

BRKJDVERFLOW 

BRKJMVZERO 

BRK_MULOVF 
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Invalid virtual address SIGSEGV EFAULT 

Read-only address SIGSEGV EACCESS 

Read beyond mapped object SIGSEGV ENXIO 

The third argument sc is a pointer to a struct sigcontext 
(defined in <sy si signal. h>) that contains the processor context 
at the time of the signal. The FORTRAN arguments are defined I 
in the same way except for the last argument which can be V 
defined either as an array of integers or as a record. 

Upon return from the signal-catching function, the receiving 
process will resume execution at the point it was interrupted. 

Before entering the signal-catching function, the value of func 
for the caught signal will be set to SIG J)FL unless the signal is 
SIGILL, SIGTRAP, or SIGPWR. This means that before exiting 
the handler, a signal call is necessary to again set the disposi- 
tion to catch the signal. 

When a signal that is to be caught occurs during a read{2), a 
write (2), an open{2\ or an ioctl(2) system call on a slow dev- 
ice (like a terminal; but not a file), during & pause (2) system 
call, or during a wait(2) system call that does not return 
immediately due to the existence of a previously stopped or 
zombie process, the signal catching function will be executed /^ 
and then the interrupted system call may return a -1 to the cal- V 
ling process with errno set to EINTR. 
Note: The signals SIGKILL and SIGSTOP cannot be caught. 

SIGNAL NOTES 

[1] If SIG_DFL is assigned for these signals, in addition to the process 
being terminated, a "core image" will be constructed in the current 
working directory of the process, if the following conditions are met: 

The effective user ID and the real user ID of the receiving 

process are equal. 

An ordinary file named core exists and is writable or can be 

created. If the file must be created, it will have the following 

properties: 

a mode of 0666 modified by the file creation mask 

[see urnask(2)] 

a file owner ID that is the same as the effective 
user ID of the receiving process. 



( 
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a file group ID that is the same as the effective 
group ID of the receiving process 

NOTE: The core file may be truncated if the resultant file size would exceed 
either ulimit [see ulimit(2)] or the process's maximum core file size [see 
setrlimit(2)]. 

[2] For the signals SIGCLD, SIGWINCH, SIGPWR, SIGURG, and SIGIO, 
the handler parameter is assigned one of three values: SIGDFL, 
SIGJGN, or a function address. The actions prescribed by these 
values are: 

SIGDFL - ignore signal 

The signal is to be ignored. 

SIGJGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the 
calling process's child processes will not create zombie 
processes when they terminate [see exit(2)]. 

function address - catch signal 

If the signal is SIGPWR, SIGURG, SIGIO, or SIGWINCH, 
the action to be taken is the same as that described above 
for a handler parameter equal to function address. The 
same is true if the signal is SIGCLD with one exception: 
while the process is executing the signal-catching func- 
tion, all terminating child processes will be queued. The 
wait system call removes the first entry of the queue. If 
the signal system call is used to catch SIGCLD, the signal 
handler must be re-attached when exiting the handler, and 
at that time-if the queue is not empty-SIGCLD is re- 
raised before signal returns. See wait(2). 

In addition, SIGCLD affects the wait and exit system calls as follows: 
wait If the handler parameter of SIGCLD is set to SIGJGN and 
a wait is executed, the wait will block until all of the cal- 
ling process's child processes terminate; it will then return 
a value of -1 with errno set to ECHILD. 

exit If in the exiting process's parent process the handler 
parameter of SIGCLD is set to SIGJGN, the exiting pro- 
cess will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the 
pipeline the parent of the proceeding processes. A process that may 
be piped into in this manner (and thus become the parent of other 
processes) should take care not to set SIGCLD to be caught. 
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[3] SIGPOLL is issued when a file descriptor corresponding to a 
STREAMS [see intro(2)] file has a "selectable" event pending. A pro- 
cess must specifically request that this signal be sent using the 
IJSETSIG ioctl call. Otherwise, the process will never receive SIG- 
POLL. 

[4] SIGEMT is never generated on an IRIS-4D system. I 

[5] SIGTRAP is generated for breakpoint instructions, overflows, divide 
by zeros, range errors, and multiply overflows. The second argument 
code gives specific details of the cause of the signal. Possible values 
are described in <sy si signal. h>. 

[6] The signals SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU and SIGCONT 
are used by command interpreters like the C shell [see csh(l)] to pro- 
vide job control. The first four signals listed will cause the receiving 
process to be stopped, unless the signal is caught or ignored. 
SIGCONT causes a stopped process to be resumed. SIGTSTP is sent 
from the terminal driver in response to the SWTCH character being 
entered from the keyboard [see termio(l)l SIGTTIN is sent from the 
terminal driver when a background process attempts to read from its 
controlling terminal. If SIGTTIN is ignored by the process, then the 
read will return EIO. SIGTTOU is sent from the terminal driver when 
a background process attempts to write to its controlling terminal when ^ 
the terminal is in TOSTOP mode. If SIGTTOU is ignored by the pro- |^ 
cess, then the write will succeed regardless of the state of the control- 
ling terminal. 

EXAMPLES 

This is an example in FORTRAN: 

#include <sys/signal.h> 

EXTERNAL FPROC 
INTEGER SIGNAL 
INTEGER CPADDR 

I = SIGNAL(SIGTERM, FPROC, -1) 
J = SIGNAL(SIGINT, 0, CPADDR) 

The first call to signal sets up the FORTRAN function fproc as the signal- 
handling routine for SIGTERM. The second call sets up a C function whose I 
address is in the variable cpaddr as the signal-handling routine for SIGINT. V 
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NOTES 

signal will not catch an invalid function argument, func, and results are 
undefined when an attempt is made to execute the function at the bad 
address. 

SIGKILL will immediately terminate a process, regardless of its state. 
Processes which are stopped via job control (typically <Ctrl>-Z) will not act 
upon any delivered signals other than SIGKILL until the job is restarted. 
Processes which are blocked via a blockproc system call will unblock if 
they receive a signal which is fatal (i.e., a non-job-control signal which the 
are NOT catching), but will still be stopped if the job of which they are a 
part is stopped. Only upon restart will they die. Any non-fatal signals 
received by a blocked process will NOT cause the process to be unblocked 
(an unblockproc(2) or unblockprocall(2) system call is necessary). 

A call to signal cancels a pending signal sig except for a pending SIGKILL 
signal. 

[EINVAL] signal will fail if sig is an illegal signal number, includ- 

ing SIGKILL and SIGSTOP. 

[EINVAL] signal will fail if an illegal operation is requested (for 

example, ignoring SIGCONT, which is ignored by 
default). 

After a fork (2) the child inherits all handlers and signal masks, but not the 
set of the pending signals. 

The exec (2) routines reset all caught signals to the default action; ignored 
signals remain ignored; the blocked signal mask is unchanged and pending 
signals remain pending. 

SEE ALSO 

intro(2), blockproc(2), kill(2), pause(2), ptrace(2), sigaction(2), sigset(2), 
wait(2), setjmp(3C), sigvec(3B). 
kill(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, signal returns the previous value of func for 
the specified signal sig. Otherwise, a value of SIGJERR is returned and 
errno is set to indicate the error. SIG_ERR is defined in the header file 
<sy si signal. h>. 

WARNINGS 

Signals raised by the instruction stream, SIGILL, SIGEMT, SIGBUS, SIG- 
SEGV will cause infinite loops if their handler returns, or the action is set to 
SIG IGN. 
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WARNING 

The POSDC signal routines (sigaction(2) 9 sigpending(2) 9 sigprocmask(2), 
sigsuspend{2\ sig$etjmp(3)), and the 4.3BSD signal routines (sigvec(3B\ 
signalQB), sigblock(3B), sigpause(3B\ sigsetmaskQB)) must NEVER be 
used with signal{2) or sigset(2). 

Before entering the signal-catching function, the value of func for the | 
caught signal will be set to SIG J)FL unless the signal is SIGXLL, SIGTRAP, V 
or SIGPWR. This means that before exiting the handler, a signal call is 
necessary to again set the disposition to catch the signal. 

Note that handlers installed by signal execute with no signals blocked, not 
even the one that invoked the handler. 



c 
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NAME 

sigset, sighold, sigrelse, sigignore, sigpause - signal management (System 

FORTRAN SYNOPSIS 

integer *4 function sighold (sig) 
integer *4 sig 

integer *4 function sigrelse (sig) 
integer *4 sig 

integer *4 function sigignore (sig) 
integer *4 sig 

integer *4 function sigpause (sig) 
integer *4 sig 

DESCRIPTION 

These functions provide signal management for application processes, sig- 
set specifies the system signal action to be taken upon receipt of signal sig. 
This action is either calling a process signal-catching handler func or per- 
forming a system-defined action. 

sighold and sigrelse are used to establish critical regions of code, sighold is 
analogous to raising the priority level and deferring or holding a signal until 
the priority is lowered by sigrelse. sigrelse restores the system signal 
action to that specified previously by sigset. 

sigignore sets the action for signal sig to SIG IGN (see below). 

sigpause suspends the calling process until it receives a signal, the same as 
pause (2). However, if the signal sig had been received and held, it is 
released and the system signal action taken. This system call is useful for 
testing variables that are changed on the occurrence of a signal. The correct 
usage is to use sighold to block the signal first, then test the variables. If 
they have not changed, then call sigpause to wait for the signal. 

Sig can be assigned any one of the following values except SIGKILL and 
SIGSTOP: 

SIGHUP 01 hangup 

SIGINT 02 interrupt 

SIGQUTT 03 [1] quit 

SIGILL 04 l illegal instruction (not reset when caught) 

SIGTRAP 05 m[5] trace trap (not reset when caught) 

SIGABRT 06 [11 abort 

SIGEMT 07 [1]t4] EMT instruction 

SIGFPE 08 [1] floating point exception 
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SIGKILL 

SIGBUS 

SIGSEGV 

SIGSYS 

SIGPBPE 

SIGALRM 

SIGTERM 

SIGUSR1 

SIGUSR2 

SIGCLD 

SIGPWR 

SIGSTOP 

SIGTSTP 

SIGPOLL 

SIGIO 

SIGURG 

SIGWINCH 

SIGVTALRM 

SIGPROF 

SIGCONT 

SIGTTIN 

SIGTTOU 

SIGXCPU 

SIGXFSZ 



09 
10 1 
11 
12 
13 
14 
15 
16 
17 



,[l] 
[1] 
[l] 



18 
19 1 
20 1 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 1 
31 
32 



[2] 



( [6] 
[6] 
( [3] 
[2] 
[2] 
■12) 



16] 
|[6] 
J6] 



kill (cannot be caught or ignored) 

bus error 

segmentation violation 

bad argument to system call 

write on a pipe with no one to read it 

alarm clock 

software termination signal 

user-defined signal 1 

user-defined signal 2 

death of a child 

power fail (not reset when caught) 

stop (cannot be caught or ignored) 

stop signal generated from keyboard 

selectable event pending 

input/output possible 

urgent condition on 10 channel 

window size changes 

virtual time alarm 

profiling alarm 

continue after stop (cannot be ignored) 

background read from control terminal 

background write to control terminal 

cpu time limit exceeded [see setrlimit(2)] 

file size limit exceeded [see setrlimit(2)] 



( 



( 



Func is assigned one of four values: SIGJDFL, SIGJGN, or SIG JIOLD, 
which are macros (defined in <syslsignalh>) that expand to constant 
expressions, or a function address. 
The actions prescribed by its value are as follows: 

SIG J)FL - terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be 
terminated with all of the consequences outlined in exit (2). See 
SIGNAL NOTES [1] below. 

SIGJGN- ignore signal 

The signal sig is to be ignored. 

Note: the signals SIGKILL, SIGSTOP and SIGCONT cannot be 
ignored. 

SIGJHOLD - hold signal £ 

The signal sig is to be held upon receipt. Any pending signal \ 
of this type remains held. Only one signal of each type is held. 
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function address - catch signal 

Upon receipt of the signal sig, the receiving process is to exe- 
cute the signal-catching function whose address is specified via 
this parameter. The function will be invoked as follows: 

handler (int sig, int code, struct sigcontext *sc); 

Where handler is the specified function-name, code is valid 
only in the following cases: 

Condition Signal Code 



User breakpoint SIGTRAP 

User breakpoint SIGTRAP 

Integer overflow SIGTRAP 

Divide by zero SIGTRAP 

Multiply overflow SIGTRAP 

Invalid virtual address SIGSEGV 

Read-only address SIGSEGV 
Read beyond mapped object SIGSEGV 



BRKJJSERBP 

BRKJSSTEPBP 

BRKOVERFLOW 

BRK_DIVZERO 

BRK_MULOVF 

EFAULT 

EACCESS 

ENXIO 



The third argument sc is a pointer to a struct sigcontext 
(defined in <sy si signal. h>) that contains the processor context 
at the time of the signal. The FORTRAN arguments are 
defined in the same way except for the last argument which can 
be defined either as an array of integers or as a record. 

Before the handler is invoked the signal action will be changed 
to SIGJHOLD. 

The signal-catching function remains installed after it is 
invoked. During normal return from the signal-catching 
handler, the system signal action is restored to func and any 
held signal of this type released. If a non-local goto (longjmp) 
is taken, then sigrelse must be called to restore the system sig- 
nal action and release any held signal of this type. 

Upon return from the signal-catching function, the receiving 
process will resume execution at the point it was interrupted. 
See WARNINGS below. 

When a signal that is to be caught occurs during a read{2), a 
write{2\ an open(2), or an ioctl(2) system call on a slow dev- 
ice (like a terminal; but not a file), during a pause (2) system 
call, or during a wait(2) system call that does not return 
immediately due to the existence of a previously stopped or 
zombie process, the signal catching function will be executed 
and then the interrupted system call may return a -1 to the 



April! 990 



-3- 



Version 3.0 



c 



SIGSET(2) Silicon Graphics SIGSET(2) 

calling process with errno set to EINTR. 

Note: The signals SIGKILL and SIGSTOP cannot be caught. 

SIGNAL NOTES 

[1] If SIG_DFL is assigned for these signals, in addition to the process 
being terminated, a "core image" will be constructed in the current 
working directory of the process, if the following conditions are met: 

The effective user ID and the real user ID of the receiving 
process are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following 
properties: 

a mode of 0666 modified by the file creation mask 

[see umask(2)] 

a file owner ID that is the same as the effective 
user ID of the receiving process. 

a file group ID that is the same as the effective 
group ID of the receiving process 

NOTE: The core file may be truncated if the resultant file size would exceed 

either ulimit [see ulimit(2)] or the process's maximum core file size [see 

setrlimit(2)]. 

[2] For the signals SIGCLD, SIGWINCH, SIGPWR, SIGURG, and SIGIO, 
the handler parameter is assigned one of three values: SIGJ)FL, 
SIGJGN, or a function address. The actions prescribed by these 
values are: 

SIG JDFL - ignore signal 

The signal is to be ignored. 

SIGJGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the 
calling process's child processes will not create zombie 
processes when they terminate [see exit(2)]. 

function address - catch signal 

If the signal is SIGPWR, SIGWINCH, SIGURG, or SIGIO, 
the action to be taken is the same as that described above 
for a handler parameter equal to function address. The ^ 
same is true if the signal is SIGCLD with one exception: ■ 
while the process is executing the signal-catching func- 
tion, all terminating child processes will be queued. The 
wait system call removes the first entry of the queue. To 
ensure that no SIGCLD 's are missed while executing in a 
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SIGCLD handler, it is necessary to call sigset to re-attach 
the handler before exiting from it, and at that time-if the 
queue is not empty-SIGCLD is re-raised before sigset 
returns. See wait(2). If the signal handler is simply exit- 
ted from, then SIGCLD will NOT be re-raised automati- 
cally. 

In addition, SIGCLD affects the wait and exit system calls as follows: 

wait If the handler parameter of SIGCLD is set to SIG JGN and 
a wait is executed, the wait will block until all of the cal- 
ling process's child processes terminate; it will then return 
a value of -1 with err no set to ECHILD. 

exit If in the exiting process's parent process the handler 

parameter of SIGCLD is set to SIG JGN, the exiting pro- 
cess will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the 
pipeline the parent of the proceeding processes. A process that may 
be piped into in this manner (and thus become the parent of other 
processes) should take care not to set SIGCLD to be caught. 

[3] SIGPOLL is issued when a file descriptor corresponding to a 
STREAMS [see intro(2)] file has a "selectable" event pending. A pro- 
cess must specifically request that this signal be sent using the 
I_SETSIG ioctl call. Otherwise, the process will never receive SIG- 
POLL. 

[4] SIGEMT is never generated on an IRIS-4D system. 

[5] SIGTRAP is generated for breakpoint instructions, overflows, divide 
by zeros, range errors, and multiply overflows. The second argument 
code gives specific details of the cause of the signal. Possible values 
are described in <sys/signal.h>. 

[6] The signals SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU and SIGCONT 
are used by command interpreters like the C shell [see csh(l)] to pro- 
vide job control. The first four signals listed will cause the receiving 
process to be stopped, unless the signal is caught or ignored. 
SIGCONT causes a stopped process to be resumed. SIGTSTP is sent 
from the terminal driver in response to the SWTCH character being 
entered from the keyboard [see termio(l)]. SIGTTIN is sent from the 
terminal driver when a background process attempts to read from its 
controlling terminal. If SIGTTIN is ignored by the process, then the 
read will return EIO. SIGTTOU is sent from the terminal driver when 
a background process attempts to write to its controlling terminal when 
the terminal is in TOSTOP mode. If SIGTTOU is ignored by the 
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process, then the write will succeed regardless of the state of the con- 
trolling terminal. 

EXAMPLES 

This is an example in FORTRAN: 

#include <sys/signal.h> I 

EXTERNAL FPROC 
INTEGER SIGNAL 
INTEGER CPADDR 

I = SIGNAL(SIGTERM, FPROC, -1) 
J = SIGNAL(SIGINT, 0, CPADDR) 

The first call to signal sets up the FORTRAN function fproc as the signal- 
handling routine for SIGTERM. The second call sets up a C function whose 
address is in the variable cpaddr as the signal-handling routine for SIGINT. 



NOTES 



SIGKILL will immediately terminate a process, regardless of its state. 
Processes which are stopped via job control (<ctrl>z) will not act upon any 
delivered signals other than SIGKILL until the job is restarted. Processes / 
which are blocked via a blockproc system call will unblock if they receive a V 
signal which is fatal (i.e. a non-job-control signal which the are NOT catch- 
ing), but will still be stopped if the job of which they are a part is stopped. 
Only upon restart will they die. Any non-fatal signals received by a 
blocked process will NOT cause the process to be unblocked (an unblock- 
proc or unblockprocall system call is necessary). 

After a/brifc(2) the child inherits all handlers and signal masks, but not the 
set of pending signals. 

The exec{2) routines reset all caught signals to the default action; ignored 
signals remain ignored, the blocked signal mask is unchanged and pending 
signals remain pending. 

sigset will fail if one or more of the following are true: 

[EINVAL] Sig is an illegal signal number (including SIGKILL and 

SIGSTOP) or the default handling of sig cannot be 
changed. | 

[EINVAL] The requested action is illegal (e.g. ignoring SIGCONT, 

which is ignored by default). 
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[EINTR] A signal was caught during the system call sigpause. 

DIAGNOSTICS 

Upon successful completion, sigset returns the previous value of the system 
signal action for the specified signal sig. Otherwise, a value of SIGERR is 
returned and errno is set to indicate the error. SIGERR is defined in 
<syslsignal.h>. 

For the other functions, upon successful completion, a value of is 
returned. Otherwise, a value of -1 is returned and errno is set to indicate 
the error. 

SEE ALSO 

csh(l), kill(2), pause(2), setrlimit(2), signal(2), ulimit(2), wait(2), sigac- 
tion(2), setjmp(3C), sigvec(3B), blockproc(2). 

WARNINGS 

Signals raised by the instruction stream, SIGILL, SIGEMT, SIGBUS, SIG- 
SEGV will cause infinite loops if their handler returns, or the action is set to 
SIGJGN. 

WARNING 

The POSDC signal routines (sigaction(2\ sigpending(2), sigprocmask(2) 9 
sigsuspend(2\ sigsetjmpQ)), and the 4.3BSD signal routines (sigvec(3B), 
signalQB), sigblock(3B), sigpauseQB), sigsetmask{3B)) must NEVER be 
used with signal(2) or sigset(2). 
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NAME 

socket - create an endpoint for communication 

FORTRAN SYNOPSIS 

integer *4 function socket (domain, type, protocol) 
integer *4 domain, type, protocol 

DESCRIPTION 

Socket creates an endpoint for communication and returns a descriptor. 

The domain parameter specifies a communications domain within which 
communication will take place; this selects the protocol family which 
should be used. The protocol family generally is the same as the address 
family for the addresses supplied in later operations on the socket These 
families are defined in the include file <sy s/ socket. h>. The currently 
understood formats are: 

PFJNET (DARPA Internet protocols) 

PF_R AW (Link-level protocols) 

PFJJNIX (43BSD UNIX internal protocols) 

The following are defined but currently unimplemented: 

PF_NS (Xerox Network Systems protocols), and 

PFJMPLINK (IMP 4 *host at IMP" link layer). 

The socket has the indicated type, which specifies the semantics of com- I 
munication. Currently defined types are: 

SOCKJSTREAM 

SOCKJXJRAM 

SOCK_RAW 

SOCK.SEQPACKET 

SOCK_RDM 
A SOCKJSTREAM type provides sequenced, reliable, two-way connection 
based byte streams. An out-of-band data transmission mechanism may be 
supported. A SOCK_DGRAM socket supports datagrams (connectionless, 
unreliable messages of a fixed (typically small) maximum length). 
SOCKJRAW sockets, which are available only to the super-user, provide 
access to internal network protocols and interfaces. The types 
SOCK_SEQPACKET and SOCK_RDM are currently unimplemented. 

The protocol specifies a particular protocol to be used with the socket. Nor- 
mally only a single protocol exists to support a particular socket type within / 
a given protocol family. However, it is possible that many protocols may V 
exist, in which case a particular protocol must be specified in this manner. 
The protocol number to use is particular to the "communication domain" 
in which communication is to take place; see getprotoent(3N). 
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Sockets of type SOCK JSTREAM are full-duplex byte streams, similar to 
pipes. A stream socket must be in a connected state before any data may be 
sent or received on it. A connection to another socket is created with a con- 
nect{2) call. Once connected, data may be transferred using read(2) and 
write (?) calls or some variant of the send(2) and recv{2) calls. Note that for 
the read and recv -style calls, the number of bytes actually read may be less 
than the number requested. When a session has been completed a close (2) 
may be performed. Out-of-band data may also be transmitted as described 
in send(2) and received as described in recv (2). 

The communications protocols used to implement a SOCKJSTREAM 
insure that data is not lost or duplicated. If a piece of data for which the 
peer protocol has buffer space cannot be successfully transmitted within a 
reasonable length of time, then the connection is considered broken and 
calls will indicate an error with -1 returns and with ETIMEDOUT as the 
specific code in the global variable errno. The protocols optionally keep 
sockets "warm" by forcing transmissions roughly every minute in the 
absence of other activity. An error is then indicated if no response can be 
elicited on an otherwise idle connection for a extended period (e.g. 5 
minutes). A SIGPIPE signal is raised if a process sends on a broken stream; 
this causes naive processes, which do not handle the signal, to exit. 

SOCKJXjRAM and SOCK_RAW sockets allow sending of datagrams to 
correspondents named in send(2) calls. Datagrams are generally received 
with recyfrom{2\ which returns the next datagram with its return address. 

An fcntl(2) call can be used to specify a process group to receive a 
SIGURG signal when the out-of-band data arrives. The FIONBIO i/o con- 
trol (see ioctl(2)) or the FNDELAY fcntl (see/cnri(2)) enable non-blocking 
I/O and asynchronous notification of I/O events via SIGIO. 

The operation of sockets is controlled by socket level options. These 
options are defined in the file <sy si socket. h>. setsockopt(2) and get- 
sockopt{2) are used to set and get options, respectively. 
RETURN VALUE 

A -1 is returned if an error occurs, otherwise the return value is a descriptor 
referencing the socket. 

ERRORS 

The socket call fails if: 

[EPROTONOSUPPORT] The protocol type or the specified protocol is 

not supported within this domain. 
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[EMFILE] 
[ENFILE] 
[EACCESS] 

[ENOBUFS] 



The per-process descriptor table is full. 

The system file table is full. 

Permission to create a socket of the specified 
type and/or protocol is denied. 

Insufficient buffer space is available. The 
socket cannot be created until sufficient 
resources are freed. 



( 



SEE ALSO 

accept(2), bind(2), connect(2), fcntl(2), getsockname(2), getsockopt(2), 
ioctl(2), listen(2), read(2), recv(2), select(2), send(2), socketpair(2), 

write(2) 

Network Programming chapter in the Network Communications Guide. 
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NAME 

sproc - create a new share group process 
FORTRAN SYNOPSIS 

integer*4 function sproc (entry, inh, arg) 

external entry 

integer*4 inh 

integer*4 arg 

DESCRIPTION 

The sproc system call is a variant of the standard fork{2) call. Like fork, 
sproc creates a new process that is a clone of the process that called sproc. 
The difference is that after an sproc, the new child process shares the virtual 
address space of the parent process (assuming that this sharing option is 
selected, as described below), rather than simply being a copy of the parent. 
The parent and the child each have their own program counter value and 
stack pointer, but all the text and data space is visible to both processes. 
This provides one of the basic mechanisms upon which parallel programs 
can be built. 

A group of processes created by sproc calls from a common ancestor is 
referred to as a share group or shared process group. A share group is ini- 
tially formed when a process first executes an sproc call. All subsequent 
sproc calls by either the parent or other children in his share group will add 
another process to the share group. In addition to virtual address space, 
members of a share group can share other attributes such as file tables! 
current working directories, effective userids and others described below. 

The new child process resulting from sproc(2) differs from a normally 
forked process in the following ways: 

The child's stack is set to a virtual address that doesn't overlap the 
stack of the parent process. There is a maximum stack size different 
from the maximum allowable amount of virtual space per process. 
This value may be read and set using prctl(2) or setrlimit{2). 

If the PRSADDR bit is set in inh then the new process will share ALL 
the virtual space of the parent, except the PRDA (see below). During 
a normal forlc(2), the writable portions of the process's address space 
are marked copy-on-write. If either process writes into a given page, 
then a copy is made of the page and given to the process. Thus writes 
by one process will not be visible to the other forks. With the 
PR_SADDR option of sproc(2), however, all the processes have 
read/write privileges to the entire virtual space. 
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The new process can reference the parent's stack. 
The new process has its own process data area (PRDA) which con- 
tains, among other things, the process id. Part of the PRDA is used by 
the system, part by system libraries, and part is available to the appli- 
cation program [see <sys/prctl.h>]. The PRDA is at a fixed virtual 
address in each process which is given by the constant PRDA defined 
inprctLh. 

The machine state (general/floating point registers) is not duplicated 
with the exception of the floating point control register. This means 
that if a process has enabled floating point traps, these will be enabled 
in the child process. 

The new process will be invoked as follows: 
entry(arg) 

In addition to the attributes inherited during the sproc call itself, the inh flag 
to sproc can request that the new process have future changes in any 
member of the share group be applied to itself. A process can only request 
that a child process share attributes that it itself is sharing. The creator of a 
share group is effectively sharing everything. These persisting attributes 
are selectable via the inh flag: 

PR JSADDR All virtual space attributes (shared memory, mapped files, 
data space) are shared. If one process in a share group 
attaches to a shared memory segment, all processes in the 
group can access that segment. 

PRJSFDS The open file table is kept synchronized. If one member 

of the share group opens a file, the open file descriptor 
will appear in the file tables of all members of the share 
group. Note that there is only one file pointer for each file 
descriptor shared within a shared process group. 

PRJSDIR The current and root directories are kept synchronized. If 

one member of the group issues a chdir(2) or chroot(2) 
call, the current working directory or root directory will 
be changed for all members of the share group. 

PRJSUMASK The file creation mask, umask is kept synchronized. 

PRSULIMIT The limit on maximum file size is kept synchronized. 

PRJSID The real and effective user and group ids are kept syn- 

chronized. 
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To take advantage of sharing all possible attributes, the constant PR_SALL 
may be used. 

In addition to specifying shared attributes, the inh flag can be used to pass 
flags that govern certain operations within the sproc call itself. Currently 
one flag is supported, PRJBLOCK, which causes the calling process to be 
blocked [see blockproc(2)] before returning from a successful call. This 
can be used to allow the child process access to the parent's stack without 
the possibility of collision. 

No scheduling synchronization is implied between shared processes: they 
are free to run on any processor in any sequence. Any required synchroni- 
zation must be provided by the application using locks and semaphores [see 
usinit(3P)] or other mechanisms. 

If one member of a share group exits or otherwise dies, its stack is removed 
from the virtual space of the share group. In addition, if the 
PR_SETEXITSIG option [see prctl(2)] has been enabled then all remaining 
members of the share group will be signaled. 

There are two versions of sproc, one in libca and one in libmpc.a. Users 
linking with the semaphored version of libc, libmpca, by using the -lmpc 
flag to the compiler, will have standard routines such as printf and malloc 
function properly even though two or more shared processes access them 
simultaneously. To accomplish this, a special arena is set up [see 
usinit($Pj\ to hold the locks and semaphores required. Each process in the 
share group needs access to this arena and requires a single file lock [see 
fcntl(2)]. This may require more file locks to be configured into the system 
than the default system configuration provides. 

sproc will fail and no new process will be created if one or more of the fol- 
lowing are true: 

[ENOMEM] If there is not enough virtual space to allocate a new 

stack. The default stack size is settable via prctl(2), or 
setrlimit(2). 

[EAGAIN] The system -imposed limit on the total number of 

processes under execution, {NPROC} [see intro(2)], 
would be exceeded. 

[EAGAIN] The system -imposed limit on the total number of 

processes under execution by a single user {CHILD MAX} 
[see intro (2)] , would be exceeded. 

[EAGAIN] Amount of system memory required is temporarily una- 

vailable. 
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When linked with libmpca, in addition to the above errors sproc will fail 
and no new process will be created if one or more of the following are true: 

[ENOSPC] If the size of the share group exceeds the number of 

users specified via usconfig(3P) (8 by default). Any 
changes via usconfig(3P) must be done BEFORE the first 
sproc is performed. 

[ENOLCK] There are not enough file locks in the system. 

New share group member pid # could not join I/O arena. error:<..> 

if the new share group member could not properly join 
the semaphored libc arena. The new process exits with a 
-1. 

See also the possible errors from usinit(3P). 

NOTES 

This manual entry has described ways in which processes created by sproc 
differ from those created by fork. Attributes and behavior not mentioned as 
different should be assumed to work the same way for sproc processes as 
for processes created by fork. Here are some respects in which the two 
types of processes are the same: 

The parent and child after an sproc each have a unique process id 

(pid), but are in the same process group. 

A signal sent to a specific pid in a share group [see kill(2)] will be 

received by only the process to which it was sent. Other members of 

the share group will not be affected. A signal sent to an entire process 

group will be received by all the members of the process group, 

regardless of share group affiliations [see killpg(3B)]. See prctl(2) for 

ways to alter this behavior. 

If the child process resulting from an sproc dies or calls exit(2), the 

parent process receives the SIGCLD signal [see sigset(2), sigaction(2), 

and sigvec(3&)]. 

CAVEATS 

Removing virtual space (e.g. unmapping a file) is an expensive operation 
and effectively forces all processes in the share group to single thread. 

Note that the global variable errno is shared by all processes in an sproc 
share group in which address space is a shared attribute. This means that if 
multiple processes in the group make system calls, the value of errno is no 
longer useful, since it may be overwritten at any time by a system call in 
another process in the share group. In order to allow a process in a share 
group to determine the value of errno reliably, the system call modules in 
libmpca store the error return code in a location in the PRDA that is 
private to each process in the share group, in addition to storing it in the 
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global variable errno. A library routine oserror(3C) is provided in both 
libca and libmpca that returns the current value errno for the process 
making the call. 

SEE ALSO 

blockproc(2), fcntl(2), fork(2), prctl(2), setrlimit(2), oserror(3C), 
pcreate(3C), usconfig(3P), usinit(3P). 

DIAGNOSTICS 

Upon successful completion, sproc returns the process id of the new pro- 
cess. Otherwise, a value of -1 is returned to the calling process, and errno 
is set to indicate the error. 
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NAME 

stat, lstat, fstat - get file status 

FORTRAN SYNOPSIS 

integer function stat (path, statb) 

character *(*) path _ 

integer statb (12) I 

integer function lstat (path, statb) 
character *(*) path 
integer statb (12) 

integer function fstat (lunit, statb) 
integer lunit, statb (12) 

DESCRIPTION 

Path points to a path name naming a file. Read, write or execute permis- 
sion of the named file is not required, but all directories listed in the path 
name leading to the file must be searchable, stat obtains information about 
the named file. The order and meaning of the information returned in array 
stath is identical to that returned in stat. 

lstat is like stat except in the case where the named file is a symbolic link, 
in which case lstat returns the information about the link, while stat returns 
the information about the file the link references. 

Similarly, fstat obtains information about an open file known by the file 
descriptor fildes, obtained from a successful open, creat, dupjcntl, or pipe 
system call. 

Bufis a pointer to a stat structure into which information is placed concern- 
ing the file. 

The contents of the structure pointed to by buf include the following 
members: 
f 

/* ID of device containing */ 
/* a directory entry for this file */ 
/* Inode number */ 
/* File mode; see mknod(2) */ 
/* Number of links */ 
/* User ID of the file's owner */ 
/* Group ID of the file's group */ 
/* ID of device*/ 
/* This entry is defined only for */ 
/* character special or block special files */ 
offj st_size; /* File size in bytes */ 

/* or, for fstat on block devices, */ 
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dev_t 


st_dev; 


ino_t 


stjno; 


mode J st_mode; 


short 


st__nlink; 


ushort 


st_uid; 


ushort 


st_£id; 


devj; 


st_rdev; 
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/* device size in 512-byte blocks */ 
time_t st_atime; /* Time of last access */ 
time_t stjmtime; /* Time of last data modification */ 
time_t st_ctime; /* Time of last file status change */ 

/* Times measured in seconds since */ 
/* 00:00:00 GMT, Jan. 1, 1970 */ 

}; 

st_atime 

Time when file data was last accessed. Changed by the following 
system calls: creat(2), mknod(2), pipe (2), utime{2), and read(2). 

st_mtime 

Time when data was last modified. Changed by the following sys- 
tem calls: creat(2), mknod(2), pipe (2), utime(2), and write (2). 

st_ctime 

Time when file status was last changed. Changed by the following 
system calls: chmod(2), chown{2), creat{2\ link(2), mknod(2), 
pipe (2), unlink(2) t utime(2), and write (2). 

Note: the st_size field is set for block devices only by fstat and not by stat. 
It is set only for block device files which are associated with a real disk dev- 
ice. 

stat and Istat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the 

path prefix. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX), or a path- 
name component is longer than {NAMEJfAX} . 

[ELOOP] Too many symbolic links were encountered in 

translating the pathname. 

[EFAULT] Buf or path points to an invalid address. 

fstat will fail if one or more of the following are true: 
[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), time(2), truncate(2), 
unlink(2), utime(2), utimes(3B). 
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DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned and err no is set to indicate the error. 
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NAME 

stime - set time 

FORTRAN SYNOPSIS 

integer *4 function stime (tp) 
integer *4 tp 

DESCRIPTION 

stime sets the system's idea of the time and date. Tp points to the value of 
time as measured in seconds from 00:00:00 GMT January 1, 1970. 

[EPERM] stime will fail if the effective user ID of the calling pro- 

cess is not super-user. 

SEE ALSO 

time(2), gettimeofday(3B), ctime(3C). 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

symlink - make symbolic link to a file 

FORTRAN SYNOPSIS 

integer *4 function symlink (namel, name2) 
character * (*) namel, name2 

DESCRIPTION 

A symbolic link name2 is created to namel ( name2 is the name of the file 
created, namel is the string used in creating the symbolic link). Either 
name may be an arbitrary path name; the files need not be on the same file 
system. 

RETURN VALUE 

Upon successful completion, a zero value is returned. If an error occurs, 
the error code is stored in errno and a -1 value is returned. 

ERRORS 

The symbolic link is made unless on or more of the following are true: 

[ENOTDIR] A component of the name2 prefix is not a directory. 

[ENOENT] A component of the namel prefix does not exist. 

[EEXIST] Namel already exists. 

[EACCES] A component of the namel path prefix denies search per- 

mission. 

[EROFS] The file namel would reside on a read-only file system. 

[EFAULT] Namel or namel points outside the process's allocated 

address space. 

[ELOOP] Too may symbolic links were encountered in translating 

the pathname. 

SEE ALSO 

link(2), ln(l), readlink(2), unlink(2) 
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NAME 

sync - update super block 

FORTRAN SYNOPSIS 

subroutine sync () 

DESCRIPTION 

sync causes all information in memory that should be on disk to be written 
out. This includes modified super blocks, modified i-nodes, and delayed 
block I/O. 

It should be used by programs which examine a file system, for example 
fsck, df, etc. It is mandatory before a re-boot. 

The writing, although scheduled, is not necessarily complete upon return 
from sync. 
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NAME 

sysmp - multiprocessing control 

FORTRAN SYNOPSIS 

integer *4 function sysmp (cmd, argl, arg2, arg3, arg4) 
integer *4 cmd, argl, arg2, arg3, arg4 

DESCRIPTION 

sysmp provides control/information for miscellaneous system services. 
This system call is usually used by system programs and is not intended for 
general use. The arguments argl, argl, arg3, arg4 are provided for 
command-dependent use. 
As specified by cmd, the following commands are available: 

MP JPGSXZE The page size of the system is returned [see get- 
pagesize(2)]. 

MP SCHED Interface for the schedctl(2) system call. 

MPJVPROCS Returns the number of processors physically configured. 

MP_NAPROCS Returns the number of processors that are available to 
schedule unrestricted processes. 

MPJSTAT The processor ids and status flag bits of the physically 

configured processors are copied into an array of 
pdajtat structures to which argl points. The array must 
be large enough to hold as many pdajtat structures as 
the number of processors returned by the MPJNPROCS 
sysmp command. The pdajtat structure and the various 
status bits are defined in <syslpda.h>. 

Empowers processor numbered argl to run any unres- 
tricted processes. This is the default system 
configuration for all processors. This command requires 
superuser authority. 

Restricts processor numbered argl from running any 
processes except those assigned to it by a 
MPJvfUSTRUN command, a runon(l) command or 
because of hardware necessity. This command requires 
superuser authority. 

MP_CLOCK Moves the operating system software clock handling to 
the processor numbered argl. This command requires 
superuser authority. 



MP EMPOWER 
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MPMUSTRUN Assigns the calling process to run only on the processor 
numbered argl, except as required for communications 
with hardware devices. 

MPRUNANYWHERE 

Frees the calling process to run on whatever processor 
the system deems suitable. 

MPKERNADDR Returns the address of various kernel data structures. 
The structure returned is selected by argl . The list of 
available structures is detailed in <syslsysmp.h>. This 
option is used by many system programs to avoid having 
to look in /unix for the location of the data structures. 

MPSASZ Returns the size of various system accounting structures. 

As above, the structure returned is governed by argl . 

MPSAGET1 Returns the contents of various system accounting struc- 
tures. The information is only for the processor specified 
by arg4 . As above, the structure returned is governed by 
argl . arg2 points to a buffer in the address space of the 
calling process and arg3 specifies the maximum number 
to bytes to transfer. 

MPSAGET Returns the contents of various system accounting struc- 

tures. The information is summed across all processors 
before it is returned. As above, the structure returned is 
governed by argl . argl points to a buffer in the address 
space of the calling process and arg3 specifies the max- 
imum number to bytes to transfer. 

Possible errors from sysmp are: 

[EPERM] The effective user ID is not superuser. Many of the com- 

mands require superuser privilege. 

The processor named by a MP_EMPOWER, 
MP_RESTRICT, MP_CLOCK or MP_SAGET1 command 
does not exist. 



[EINVAL] 

[EINVAL] 
[EINVAL] 

[EBUSY] 



The cmd argument is invalid. 

The argl argument to a MPJCERNADDR command is 
invalid. 

An attempt was made to restrict the only unrestricted 
processor or to restrict the master processor. 
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[EFAULT] An invalid buffer address has been supplied by the cal- 

ling process. 

SEE ALSO 

mpdmin(l), runon(l), getpagesize(2), schedctl(2). 

DIAGNOSTICS f 

Upon successful completion, the cmd dependent data is returned. Other- ^ 
wise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

uadmin - administrative control 

FORTRAN SYNOPSIS 

integer *4 function uadmin (cmd, fen, mdep) 
integer *4 cmd, fen, mdep 

DESCRIPTION 

uadmin provides control for basic administrative functions. This system 
call is tightly coupled to the system administrative procedures and is not 
intended for general use. The argument mdep is provided for machine- 
dependent use and is not defined here. 

As specified by cmd, the following commands are available: 

A_SHUTDOWN The system is shutdown. All user processes are killed, 
the buffer cache is flushed, and the root file system is 
unmounted. The action to be taken after the system has 
been shut down is specified by fen. The functions are 
generic; the hardware capabilities vary on specific 
machines. 

ADJHALT Halt the processor and turn off the power. 

AD_BOOT Reboot the system, using /unix. 

ADJBOOT Interactive reboot; user is prompted for 
system name. Not supported; it is treated 
the same as AD_HALT. 

AJREBOOT The system stops immediately without any further pro- 

cessing. The action to be taken next is specified by fen 
as above. 

A_REMOUNT The root file system is mounted again after having been 
fixed. This should be used only during the startup pro- 
cess. 

AJOLLALL All processes are killed except those belonging to the 

process group specified by fen. They are sent the signal 
specified by mdep. 

uadmin fails if any of the following are true: 
[EPERM] The effective user ID is not super-user. 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 
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A_SHUTDOWN Never returns. 

A_REBOOT Never returns. 

A.REMOUNT 

A_KILLALL 

Otherwise, a value of -1 is returned and errno is set to indicate the error. I 
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NAME 

ulimit - get and set user limits 

FORTRAN SYNOPSIS 

integer *4 function ulimit (cmd, newlimit) 
integer *4 cmd, newlimit 

DESCRIPTION 

This function provides for control over process limits. The cmd values 
available are: 

1 Get the regular file size limit of the process. The limit is in units of 
512-byte blocks and is inherited by child processes. Files of any size 
can be read. 

2 Set the regular file size limit of the process to the value of newlimit. 
Any process may decrease this limit, but only a process with an effec- 
tive user ID of super-user may increase the limit, ulimit fails and the 
limit is unchanged if a process with an effective user ID other than 
super-user attempts to increase its regular file size limit. [EPERM] 

3 Get the maximum possible break value [see brk(2)]. 

4 Get the current value of the maximum number of open files per pro- 
cess configured in the system. 

SEE ALSO 

brk(2), setrlimit(2), write(2). 

WARNING 

ulimit is effective in limiting the growth of regular files. Pipes are currently 
limited to 10240 bytes. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of -1 is returned and errno is set to indicate the error. 
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NAME 

umask - set and get file creation mask 

FORTRAN SYNOPSIS 

integer *4 function umask (cmask) 

integer *4 cmask _ 

DESCRIPTION |^ 

umask sets the process's file mode creation mask to cmask and returns the 
previous value of the mask. Only the low-order 9 bits of cmask and the file 
mode creation mask are used. 

SEE ALSO 

chmod(2), creat(2), mknod(2), open(2). 
mkdir(l), sh(l) in the User's Reference Manual 

DIAGNOSTICS 

The previous value of the file mode creation mask is returned. 



( 
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NAME 

umount - unmount a file system 

FORTRAN SYNOPSIS 

integer *4 function umount (file) 
character * (*) file 

DESCRIPTION 

umount requests that a previously mounted file system contained on the 
block special device or directory identified by file be unmounted. File is a 
pointer to a path name. After unmounting the file system, the directory 
upon which the file system was mounted reverts to its ordinary interpreta- 
tion. 

umount may be invoked only by the super-user. 

umount will fail if one or more of the following are true: 

[EPERM] The process's effective user ID is not super-user. 

[EINVAL] File does not exist. 

[ENOTBLK] File is not a block special device. 

[EINVAL] File is not mounted. 

[EBUSY] A file on file is busy. 

[EFAULT] File points to an illegal address. 

SEE ALSO 

mount(2). 

DIAGNOSTICS 

Upon successful completion a value of is returned. Otherwise, a value of 
-1 is returned and err no is set to indicate the error. 



April 1990 -1- Version 3.0 



UNLINK(2) 



Silicon Graphics 



UNLINK(2) 



NAME 



unlink - remove directory entry 



FORTRAN SYNOPSIS 

integer function unlink (path) 
character *(*) path 

DESCRIPTION 

unlink removes the directory entry named by the path name pointed to by 

path. 

The named file is unlinked unless one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the 

path prefix. 

[EACCES] Write permission is denied on the directory containing 

the link to be removed. 

[EACCES] The parent directory has the sticky bit set and 

the file is not writable by the user and 
the user does not own the parent directory and 
the user does not own the file and 
the user is not superuser. 

[EPERM] The named file is a directory and the effective user ID 

of the process is not super-user. 

[ENAMETOOLONG] The length of path exceeds {PATH MAX}, or a path- 
name component is longer than {NAMEJ4AX} . 

[ELOOP] Too many symbolic links were encountered in 

translating the pathname. 

[EBUSY] The entry to be unlinked is the mount point for a 

mounted file system. 

[EROFS] The directory entry to be unlinked is part of a read- 

only file system. 

[EFAULT] Path points outside the process's allocated address 

space. 

When all links to a file have been removed and no process has the file open, 
the space occupied by the file is freed and the file ceases to exist. If one or 
more processes have the file open when the last link is removed, the remo- 
val is postponed until all references to the file have been closed. 
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SEE ALSO 

close(2), link(2), open(2), rename(2), rmdir(2). 
rm(l) in the User 1 s Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of is returned. Otherwise, a value of 
-1 is returned and errno is set to indicate the error. 
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NAME 

wait, waitpid, wait3 - wait for child processes to stop or terminate 

FORTRAN SYNOPSIS 

integer function wait (status) integer status 

DESCRIPTION 

Wait functions: The wait functions suspend the calling process until one of 
the immediate children terminate, or until a child that is being traced stops 
because it has hit a break point. These system calls will return prematurely 
if a signal is received, and if a child process stopped or terminated prior to 
the call then return is immediate. If the call is successful, the process ID of 
a child is returned. The two versions differ in the type of their input param- 
eter (statptr), but the information conveyed is identical if the macros in 
<sys/waith> are used (see below description in the PARAMETERS section). 

Wait3: Wait3 is BSP's extension of wait. It provides an alternate interface 
for programs that must not block when collecting the status of child 
processes. 

Waitpid: The waitpid function is POSDC's extension of wait. The pid argu- 
ment specifies a set of child processes for which status is requested. The 
waitpid function only returns the status of a child process from this set. 

PARAMETERS _ 

Statptr (all functions): If Statptr is non-zero, 16 bits of information called I 
status are stored in the low-order 16 bits of the location pointed to by V 
statptr. Status can be used to differentiate between stopped and terminated 
child processes. If the child process terminated, status identifies the cause of 
termination and passes useful information to the parent. A more precise 
definition of the status structure is given in <sys/wait.h>. Status is inter- 
preted as follows: 

If the child process stopped, the predicate WlF8TO¥mD(* statptr) 
will evaluate to non-zero and WSTO¥SlG(*statptr) will return the 
signal number that caused the process to stop. (The high-order 8 
bits of status will contain the signal number and the low-order 8 
bits are set equal to 0177.) 

If the child process terminated due to an exit call, the predicate 
WIFEXXTED(*,tfa#?{r) will evaluate to non-zero, and 
WEXJTSTATUS(* statptr) will return the argument that the child 
process passed to jsxit or exit, or the value the child process 
returned from main [see exit (2)1 (The low-order 8 bits of status I 
will be zero and the high-order 8 bits will contain the low-order 8 ^ 
bits of the exiting argument.) 
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If the child process terminated due to a signal, the predicate 
WXFSIGNALED(*,tfaf/?/r) will evaluate to non-zero, and 
WTERM$IG(*statptr) will return the signal number that caused 
the termination. (The high-order 8 bits of status will be zero and 
the low-order 8 bits will contain the number of the signal.) In 
addition, if the low-order seventh bit (i.e., bit 0200) is set, a "core 
image" will have been produced [see signal{2)]. 

Rusage (wait3): If wcdt3's rusage parameter is non-zero, a summary of the 
resources used by the terminated process and all its children is returned 
(this information is currently not available for stopped processes). 

Pid (waitpid): 

1) If pid is equal to -1, status is requested for any child process. In 
this respect, waitpid is then equivalent to wait. 

2) lfpU is greater than zero, it specifies the process ID of a single 
child process for which status is requested. 

3) If pid is equal to zero, status is requested for any child process 
whose process group ID is equal to that of the calling process. 

4) If pid is less than -1, status is requested for any child process 
whose process group ID is equal to the absolute value of pid. 

Options (waitpid and wait3): The options argument is constructed from 
the bitwise inclusive OR of zero or more of the following flags, defined in 
the header <sys/wait.h>: 

WNOHANG The function will not suspend execution of the calling 
process if status is not immediately available for one of 
the child processes. 

WUNTRACED The status of child processes that are stopped due to a 
SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP signal, and 
whose status has not yet been reported since they 
stopped, are reported to the requesting process. 

If a parent process terminates without waiting for its child processes to ter- 
minate, the parent process ID of each child process is set to 1. This means 
the initialization process inherits the child processes [see intro(2)]. 

SIGCLD HANDLING 

IRK has three distinct version of signal routines: System V (signal(2) and 
sigset{2)\ 4.3BSD (signalQB) and sigvec(3B)\ and POSDC (sigaction(2)). 
Each version has a method by which a parent can be certain that it waits on 
all of its children even if they are executing concurrently. In each version, 
the parent installs a signal handler for SIGCLD to wait for its children, but 
the specific code differs in subtle, albeit vital, ways. Sample programs 
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below are used to illustrate each of the three methods. 

Note that System V refers to this signal as SIGCLD, whereas BSD calls it 
SIGCHLD. For compatibility with both systems they are defined to be the 
same signal number, and may therefore be used interchangeably. 

System V: System V's SIGCLD mechanism guarantees that no SIGCLD g 
signals will be lost. It accomplishes this by forcing the process to reinstall I 
the handler (via signal or sigset calls) when leaving the handler. Note that 
whereas signal(2) sets the signal disposition back to SIGJ)FL each time the 
handler is called, sigset{2) keeps it installed, so SIGCLD is the only signal 
that demands this reinstallation, and that only because the installation call 
allows the kernel to check for additional instances of the signal that 
occurred while the process was executing in the handler. The code below is 
the System V example. Note that the sigpause(2) creates a window during 
which SIGCLD is not blocked, allowing the parent to enter its handler. 

/* 

* System V example of wait-in-SIGCLD-handler usage 

*/ 

#include <signal.h> 

#include <stdio.h> 

#include <sys/wait.h> 



static void handler (int) ; 

#define NUMKIDS 4 
volatile int kids = NUMKIDS; 

main () 
{ 

int i, pid; 

sigset (SIGCLD, handler); 

sighold (SIGCLD) ; 

for (i = 0; i < NUMKIDS; i++)' { 

if (fork() == 0) { 

printf ("Child %d\n", getpidO) 
exit(0); 

} 
} 
while (kids > 0) { 

sigpause (SIGCLD) ; 

sighold (SIGCLD); 
} 
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static void 
handler (int sig) 
{ 

int pid, status; 

printf ("Parent (%d) in handler, ", getpidO); 

pid = wait (&status) ; 

kids — ; 

printf ("child %d, now %d left\n", pid, kids); 

/* 

* Now reinstall handler & cause SIGCLD to be re-raised 

* if any more children exited while we were in here. 
*/ 

sigset (SIGCLD, handler) ; 
} 

BSD: 4.3BSD solved this problem differently: instead of guaranteeing that 
no SIGCHLD signals are lost, it provides a WNOHANG option to wcdt3 that 
allows parent processes to do non-blocking waits in loops, until no more 
stopped or zombied children exist. Note that the handler must be able to 
deal with the case in which no applicable children exist; if one or more chil- 
dren exit while the parent is in the handler, all may get reaped, yet if one or 
more SIGCHLD signals arrived while the parent was in its handler, the sig- 
nal will remain pending, the parent will reenter the handler, and the wait3 
call will return 0. Note that it is not necessary to call sigvec upon exit from 
the handler. 

/* 

* BSD example of wait3-in-SIGCHLD handler usage 
*/ 

#define _BSD_SIGNALS 
#include <signal.h> 
#include <stdio.h> 
#include <sys/wait.h> 

static int handler (int) ; 

#define NUMKIDS 4 
volatile int kids = NUMKIDS; 

main () 
{ 
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int i, pid; 
struct sigvec vec; 

vec.sv_handler = handler; 
vec.sv_mask = sigmask (SIGCHLD) ; 
vec. sv_f lags =0; 

sigvec (SIGCHLD, &vec, NULL) ; 
sigsetmask (sigmask (SIGCHLD) ); 
for (i =0; i < NUMKIDS; i++) { 

if (fork() ==0) { , 

printf ("Child %d\n", getpidO); 
exit (0); 

} 
} 
while (kids > 0) { 

sigpause (0) ; 
} 



( 



> 



static int 
handler (int sig) 

{ 

int pid; 

union wait status; 



C 



printf ("Parent (%d) in handler, ", getpidO); 
while ((pid = wait3 (&status, WNOHANG, NULL)) > 0) { 

kids — ; 

printf ("child %d, now %d left\n", pid, kids); 

} 
} 

POSIX: POSDC improved on the BSD method by providing waitpid, that 
allows a parent to wait on a particular child process if desired. In addition, 
the IRIX implementation of sigaction(2) checks for zombied children upon 
exit from the system call if the specified signal was SIGCLD and the dispo- 
sition of the signal handling was changed. If zombied children exist, 
another SIGCLD is raised. This solves the problem that occurs when a 
parent creates children, but a module that it links with (typically a libc rou- | 
tine such as sy$tem(3)) creates and waits on its own children. V. 
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Two problems have classically arisen in such a scheme: 1) until the advent 
of waitpid, the called routine could not specify which children to wait on; it 
therefore looped, waiting and discarding children until the one (or ones) it 
had created terminated, and 2) if the called routine changed the disposition 
of SIGCLD and then restored the previous handler upon exit, children of the 
parent (calling) process that had terminated while the called routine exe- 
cuted would be missed in the parent, because the called routine's SIGCLD 
handler would reap and discard those children. The addition of waitpid and 
the IRIX implementation of sigaction solves both of these problems. Note 
that neither the BSD nor the System V signal routines on IRIX have these 
properties, in the interests of compatibility. 

WARNING: programs that install SIGCLD handlers that set flags instead of 
executing waitpids and then attempt to restore the previous signal handler 
(via sigaction) upon return from the handler will create infinite loops. 

/* 

* POSIX example of waitpid-in-SIGCHLD handler usage 
*/ 

#include <signal.h> 
#include <stdio.h> 
#include <sys/wait.h> 

static void handler (int) ; 

#define NUMKIDS 4 
volatile int kids = NUMKIDS; 

/* 

* If waitpid' s 1st argument is -1, it waits for any child. 
*/ 

#define ANYKID -1 

main () 
{ 

int i; 

pid_t pid; 

struct sigaction act; 

sigset_t set, empty set; 

act.sa_handler = handler; 
act.sa_mask = sigmask (SIGCHLD) ; 
act.sa_flags = 0; 



April 1990 -6- Version 3.0 



WATT(2) 



Silicon Graphics 



WATT(2) 



sigaction(SIGCHLD, &act, NULL); 
sigemptyset (&set) ; 
sigemptyset (&emptyset) ; 
sigaddset (&set, SIGCHLD) ; 
sigprocmask(SIG_BLOCK, &set, NULL) ; 
setbuf (stdout, NULL) ; 

for (i = 0; i < NUMKIDS; i++) { 
if (fork() == 0) { 

.printf ("Child %d\n", getpidO); 
exit (0) ; 
} 
} 
while (kids > 0) { 

sigsuspend(&emptyset) ; 

} 



( 



} 



static void 
handler (int sig) 

{ 

pid__t pid; 
int status; 

printf ("Parent (%d) in handler, ", getpidO); 
pid = waitpid(ANYKID, &status, WNOHANG) ; 
while (pid > 0) { 

kids — ; 

printf ("child %d, now %d left\n", pid, kids) ; 

pid = waitpid(ANYKID, fistatus, WNOHANG); 
} 



( 



DIAGNOSTICS 

Wait fails and its actions are undefined if statptr points to an invalid 
address. If wait, wait3, or waitpid return due to a stopped or terminated 
child process, the process ID of the child is returned to the calling process. 
WaitS and waitpid return if WNOHANG is specified and there are 
currently no stopped or exited children (although children DO exist). Other- 
wise, a value of -1 is returned and errno is set to indicate the error: 

[EINTR] wait, wait3, waitpid: The calling process received a sig- 

nal. 



( 



April 1990 



Version 3.0 



WATT(2) 



Silicon Graphics 



WATT(2) 



[ECHILD] wait, wait3, waitpid: The calling process has no existing 

unwaited-for child processes, waitpid: The process or 
process group specified by pid does not exist or is not a 
child of the calling process. 

[EFAULT] wait3, waitpid: The rusage or statptr arguments (where 

applicable) point to illegal addresses. 

[EINVAL] waitpid: The value of the options argument is not valid. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), pause(2), ptrace(2), signal(2), sigset(2), 
sigpause(2), sigaction(2), sigsuspend(2), sigprocmask(2), signal(3B), 
sigvec(3B), sigpause(3B). 



NOTE 



Currently, wait3 returns only the user and system time in rusage. 
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NAME 

write - write on a file 

FORTRAN SYNOPSIS 

integer *4 function write (fildes, buf, nbyte) 
integer *4 fildes 
character * (*) buf 
integer *4 nbyte 

DESCRIPTION 

fildes is a file descriptor obtained from a creatQ), open(2), dup(2)Jcntl(2) 9 
piped!), soeket(2), or socketpair{2) system call. 

write attempts to write nbyte bytes from the buffer pointed to by buf to the 
file associated with the fildes . 

On devices capable of seeking, the actual writing of data proceeds from the 
position in the file indicated by the file pointer. Upon return from write, the 
file pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the 

current position. The value of a file pointer associated with such a device is 

undefined. 

If the 0_APPEND flag of the file status flags is set, the file pointer will be set 

to the end of the file prior to each write. 

For regular files, if the OJSYNC flag of the file status flags is set, write will 
not return until both the file data and file status have been physically 
updated. This function is for special applications that require extra reliabil- 
ity at the cost of performance. For block special files, if 0_S YNC is set, the 
write will not return until the data has been physically updated. 

A write to a regular file will be blocked if mandatory file/record locking is 
set [see ckmod(2)] 9 and there is a record lock owned by another process on 
the segment of the file to be written. If neither O.NDELAY or 
0„NONBLOCK are set, the write will sleep until the blocking record lock is 
removed, otherwise (either flag set) write returns -1 and errno is set to 
EAGAIN. 

For STREAMS [see intro(2)] files, the operation of write is determined by 
the values of the minimum and maximum nbyte range ("packet size") 
accepted by the stream. These values are contained in the topmost stream 
module. Unless the user pushes [see IJFUSH in streamio(J)] the topmost 
module, these values can not be set or tested from user level. If nbyte falls | 
within the packet size range, nbyte bytes will be written. If nbyte does not V 
fall within the range and the minimum packet size value is zero, write will 
break the buffer into maximum packet size segments prior to sending the 
data downstream (the last segment may contain less than the maximum 
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packet size). If nbyte does not fall within the range and the minimum value 
is non-zero, write will fail with errno set to ERANGE. Writing a zero-length 
buffer {nbyte is zero) sends zero bytes with zero returned. 

For STREAMS files, if O.NDELAY and O.NONBLOCK are not set and the 
stream can not accept data (the stream write queue is full due to internal 
flow control conditions), write will block until data can be accepted. 
O.NDELAY or O.NONBLOCK will prevent a process from blocking due to 
flow control conditions. If O.NDELAY or O.NONBLOCK is set and the 
stream can not accept data, write will fail, returning -1 and setting errno to 
EAGAIN. If O.NDELAY or O.NONBLOCK is set and part of the buffer has 
been written when a condition in which the stream can not accept additional 
data occurs, write will terminate and return the number of bytes written. 

write will fail and the file pointer will remain unchanged if one or more of 
the following are true: 

[EAGAIN] Mandatory file/record locking was set, O.NDELAY or 

O.NONBLOCK was set, and there was a blocking record 
lock. 

[EAGAIN] Total amount of system memory available when reading 

via raw 10 is temporarily insufficient. 

[EAGAIN] Attempt to write to a stream that can not accept data with 

the O.NDELAY or O.NONBLOCK flag set 

[EB ADF] fildes is not a valid file descriptor open for writing. 

[EDEADLK] The write was going to go to sleep and cause a deadlock 

situation to occur. 

[EFAULT] buf points outside the process's allocated address space. 

[EFBIG] An attempt was made to write a file that exceeds the 

process's file size limit or the maximum file size [see 
ulimit(2)]. 

[EINTR] A signal was caught during the write system call. 

[EINVAL] Attempt to write to a stream linked below a multiplexor. 

[ENOLCK] The system record lock table was full, so the write could 

not go to sleep until the blocking record lock was 
removed. 

[ENOSPC] During a write to an ordinary file, there is no free space 

left on the device. 
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[ENXIO] A hangup occurred on the stream being written to. 

[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for 
reading by any process. 

[ERANGE] Attempt to write to a stream with nhyte outside specified 

minimum and maximum write range, and the minimum 
value is non-zero. 

If a write requests that more bytes be written than there is room for (e.g., 
the ulimit [see ulimit(2) mdsetrlimit(2)] or the physical end of a medium), 
only as many bytes as there is room for will be written. For example, sup- 
pose there is space for 20 bytes more in a file before reaching a limit. A 
write of 512-bytes will return 20. The next write of a non-zero number of 
bytes will give a failure return (except as noted below). 

If the file being written is a pipe (or FIFO) and the 0_NDELAY flag of the 
file flag word is set, then write to a full pipe (or FIFO) will return a count of 
0. If the file being written is a pipe (or FIFO) and the 0_NONBLOCK flag of 
the file flag word is set, then write to a full pipe (or FIFO) will return -1 and 
set errno to EAGAIN. Otherwise (O.NDELAY and O.NONBLOCK clear), 
writes to a full pipe (or FIFO) will block until space becomes available. 

A write to a STREAMS file can fail if an error message has been received at 

the stream head. In this case, errno is set to the value included in the error i 

message. 

CAVEATS 

Due to the different semantics of O.NDELAY and 0_NONBLOCK in the 
case of pipes or FIFOs, these flags must not be used simultaneously. 

SEE ALSO 

creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2), pipe(2), setrlimit(2), 
ulimit(2). 

DIAGNOSTICS 

Upon successful completion the number of bytes actually written is 
returned. Otherwise, -1 is returned and errno is set to indicate the error. 
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NAME 

abort - terminate Fortran program 

SYNOPSIS 

call abort ( ) 

DESCRIPTION 

abort terminates the program which calls it, closing all open files truncated 
to the current position of the file pointer. The abort usually results in a core 
dump. 

DIAGNOSTICS 

When invoked, abort prints "Fortran abort routine called" on the standard 
error output. The shell prints the message "abort - core dumped" if a core 
dump results. 

SEE ALSO 

abort(3C). 

sh(l) in the User's Reference Manual 
ORIGIN 

AT&T V.3 
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NAME 

abs, iabs, dabs, cabs, zabs, iiabs, jiabs - FORTRAN absolute value 

SYNOPSIS 

integer il, i2 

real rl, r2 ^- 

double precision dpi, dp2 I 

complex cxl, cx2 ^ 

double complex dxl, dx2 

integer*2 iil, ii2 

integer*4 jil, ji2 

r2 = abs(rl) 

i2 = iabs(il) 
i2 = abs(il) 

dp2 = dabs(dpl) 
dp2 = abs(dpl) 

cx2 = cabs(cxl) 
cx2 = abs(cxl) 

dx2 = zabs(dxl) 
dx2 = abs(dxl) 

ii2 = iiabs(iil) f 

ii2 = abs(iil) ^ 

ji2 = jiabs(jil) 

ji2 = abs(jil) 

DESCRIPTION 

abs is the family of absolute value functions, iabs returns the integer abso- 
lute value of its integer argument. It accepts either integer*2 or integer*4 
arguments and the result is the same type, dabs returns the double- 
precision absolute value of its double-precision argument, cabs returns the 
complex absolute value of its complex argument, zabs returns the double- 
complex absolute value of its double-complex argument, iiabs returns the 
integer*2 absolute value of its integer*2 argument, jiabs returns the 
integerM absolute value of its integer*4 argument. The generic form abs 
returns the type of its argument. 

SEE ALSO 

floor(3M). 

CAVEAT 

In two's-complement integer (integer*2 or integer*4) representation the 
absolute value of the negative integer with largest magnitude is undefined. 
Some implementations trap this error, but others simply ignore it. 
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NAME 

acos, dacos, acosd, dacosd - FORTRAN arccosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

real*4 r3, r4 

real*8 dp3, dp4 

r2 = acos(rl) 

dp2 = dacos(dpl) 
dp2 = acos(dpl) 

r4 = acosd(r3) 

dp4 = dacosd(dp3) 
dp4 = acosd(dp3) 

DESCRIPTION 

acos returns the real arccosine of its real argument, dacos returns the 
double-precision arccosine of its double-precision argument. The absolute 
value of the argument for these routines must be less than or equal to one. 
The result is in radians and the range is less than or equal to one. The gen- 
eric form acos may be used with impunity as its argument will determine 
the type of the returned value. 

acosd returns the real*4 arccosine of its real*4 argument, dacosd returns 
the real*8 arccosine of its real88 argument. The absolute value of the argu- 
ment for these routines must be less than or equal to one and the result is in 
degrees. The generic form acosd may be used with impunity for acosd 
dacosd as its argument will determine the type of the returned value. 
SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

aint, dint, iint, jint, iidint, jidint - FORTRAN integer part intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 ^ 

real*4 r3 I 

real*8 dp3 

integer*2 ii 

integer*4 ji 

r2 = aint(rl) 

dp2 = dint(dpl) 

ii = iint(r3) 

ji = jint(r3) 

ii = iidint(dp3) 

ji = jidint(dp3) 

DESCRIPTION 

aim returns the truncated value of its real argument in a real, dint returns 



the truncated value of its double-precision argument as a double-precision 
value, iint returns the truncated value of its real*4 argument in a integer*2. 
jint returns the truncated value of its real*4 argument in a integer*4. iidint 
returns the truncated value of its real*8 argument in a integer*2. jidint 
returns the truncated value of its real*8 argument in a integer*4. 



c 



ORIGIN 

MIPS Computer Systems 
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NAME 

alarm - execute a subroutine after a specified time 
SYNOPSIS 

integer function alarm (time, proc) 

integer time 

external proc 

DESCRIPTION 

This routine arranges for subroutine proc to be called after time seconds. If 
time is "0", the alarm is turned off and no routine will be called. The 
returned value will be the time remaining on the last alarm. 

FILES 

/usr/lib/UbU77.a 

SEE ALSO 

sleep(3F), signal(3F) 

BUGS 

Alarm and sleep interact. If sleep is called after alarm, the alarm process 
will never be called. SIGALRM will occur at the lesser of the remaining 
alarm time or the sleep time. 

ORIGIN 

MIPS Computer Systems 
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NAME 

asin, dasin, asind, dasind - FORTRAN arcsine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 ^ 

real*4 r3, r4 f 

real*8 dp3, dp4 v 

r2 = asin(rl) 

dp2 = dasin(dpl) 
dp2 = asin(dpl) 

r4 = asind(r3) 

dp4 = dasind(dp3) 
dp4 = asind(dp3) 

DESCRIPTION 

asin returns the real arcsine of its real argument, dasin returns the double- 
precision arcsine of its double-precision argument. The absolute value of 
the arguments for asin and dasin must be less than or equal to one. The 
result is in radians and is in the range -p/2 < result < p/2. The generic form 
asin may be used with impunity as it derives its type from that of its argu- 
ment. 



asind returns the real*4 arcsine of its real*4 argument, dasind returns the 
real*8 arcsine of its real*8 argument. The absolute value of the arguments 
for asind and dasind must be less than or equal to one. The result is in 
degrees. The generic form asind may be used with impunity as it derives 
its type from that of its argument. 



c 



SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

atan, datan, atand, datand - FORTRAN arctangent intrinsic function 
SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

real*4 r3, r4 

real*8 dp3, dp4 

r2 = atan(rl) 

dp2 = datan(dpl) 
dp2 = atan(dpl) 

r4 = atand(r3) 

dp4 = datand(dp3) 
dp4 = atand(dp3) 

DESCRIPTION 

atan returns the real arctangent of its real argument, datan returns the 
double-precision arctangent of its double-precision argument. The generic 
form atan may be used with a double-precision argument returning a 
double-precision value. The result of atan and datan is in radians. 

atand returns the real*4 arctangent of its real*4 argument, datand returns 
the real*8 arctangent of its real*8 argument. The generic form atand may 
be used with a real*8 argument returning a real*8 value. The result of 
atand and datand is in degrees. 

SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

atan2, datan2, atan2d, datan2d - FORTRAN arctangent intrinsic function 

SYNOPSIS 

real rl, r2, r3 

double precision dpi, dp2, dp3 

real*4 r4, r5, r6 

real*8 dp4, dp5, dp6 

r3 = atan2(rl, r2) 

dp3 = datan2(dpl, dp2) 
dp3 = atan2(dpl, dp2) 

r6 = atan2d(r4, r5) 

dp6 = datan2d(dp4, dpS) 
dp6 = atan2d(dp4, dpS) 

DESCRIPTION 

atan2 returns the arctangent of argllarg2 as a real value. datan2 returns 
the double-precision arctangent of its double-precision arguments. The 
generic form atari! may be used with impunity with double-precision argu- 
ments. If the value of the first argument of atan2 or datan2 is positive, the 
result is positive. When the value of the first argument is zero, the result is 
zero if the second argument is positive and P if the second argument is 
negative. If the value of the first argument is negative, the result is nega- 
tive. If the value of the second argument is zero, the absolute value of the 
result is P/2. Both arguments must not have the value zero. The result of 
atan2 and datan2 is in radians. 

atan2d returns the arctangent of argil arg2 as a real*4 value. datan2d 
returns the real*8 arctangent of its real*8 arguments. The generic form 
atan2d may be used with impunity with real*8 arguments. If the value of 
the first argument of atan2d or datan2d is positive, the result is positive. 
When the value of the first argument is zero, the result is zero if the second 
argument is positive and P if the second argument is negative. If the value 
of the first argument is negative, the result is negative. If the value of the 
second argument is zero, the absolute value of the result is P/2. Both argu- 
ments must not have the value zero. The result of atanld and datan2d is L. 
the range: -180 degrees < result < 180 degrees. 

SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

bool: iand, and, iior, ior, or, jior, inot, jnot, not, iieor, jieor, ieor, xor, iishft, 
jishft, ishft, lshift, rshift, iishftc, jishftc, ishftc, iibits, jibits, ibits, iibset, jib- 
set, ibset, bitest, bjtest, btest, iibclr, jibclr, ibclr, mvbits - FORTRAN bit- 
wise boolean functions 

SYNOPSIS 

integer i, k, 1, m, n, len 
integer*2 SI, ii2, ii3 
logical b 
logical*2 c 

= iand(m, n) 
= and(m, n) 

ii3 = iior(iil, ii2) 
= ior(m, n) 
= or(m, n) 
= jior(m, n) 

ii3 = inot(iil) 
= jnot(m) 
= not(m) 

ii3 = iieor(iil, ii2) 
= jieor(m, n) 
= ieor(m, n) 
= xor(m, n) 

ii3 = iishft(iil, ii2) 
= jishft(m, k) 
= ishft(m, k) 
= lshift(m, k) 
= rshift(m, k) 

ii3 = iishftc(iil, ii2, len) 
= jishftc(m, k, len) 
= ishftc(m, k, len) 

ii3 = iibits(iil, ii2, len) 
= jibits(m, k, len) 
= ibits(m, k, len) 

ii3 = iibset(iil, ii2) 
= jibset(n, k) 
= ibset(n, k) 
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c = bitest(iil, ii2) 
b = bjtest(n, k) 
b = btest(n, k) 

13 = iibcir(iil, ii2) 
= jibclr(n, k) 
= ibclr(n, k) 

call mvbits(m, k, len, n, 1) 

DESCRIPTION 

bool is the general name for the bit field manipulation intrinsic functions 
and subroutines from the FORTRAN Military Standard (MIL-STD-1753). 

and, or and xor return the value of the binary operations on their arguments. 
not is a unary operator returning the one's complement of its argument ior, 
iand, not, ieor - return the same results as and, or, not, and xor. 

Ishift and rshift return the value of the first argument shifted left or right, 
respectively, the number of times specified by the second (integer) argu- 
ment 

ishft, ishftc - m specifies the integer to be shifted, k specifies the shift 
count, k > indicates a left shift k = indicates no shift, k < indicates a 
right shift In ishft, zeros are shifted in. In ishftc, the rightmost len bits are 
shifted circularly k bits. If k is greater than the machine word-size, ishftc 
will not shift 

iand, ior, not, ieor, and ishft accept either integer*2 or integer*4 arguments 
and the result is the same type. When one of these intrinsics is specified as 
an argument in a subroutine call or function reference, the compiler sup- 
plies either an integer*2 or integer*4 function depending on the 42 com- 
mand line option. 

Bit fields are numbered from right to left and the rightmost bit position is 
zero. The length of the len field must be greater than zero. 

ihits - extract a subfield of len bits from m starting with bit position k and 
extending left for len bits. The result field is right justified and the remain- 
ing bits are set to zero. 

btest - The kth bit of argument n is tested. The value of the function is 
.TRUE, if the bit is a 1 and .FALSE, if the bit is 0. 

ihset - the result is the value of n with the kth bit set to 1. 

ibclr - the result is the value of n with the kth bit set to 0. 
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mvhits - ten bits are moved beginning at position k of argument m to posi- 
tion 1 of argument n. 

ORIGIN 

MIPS Computer Systems 
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NAME 

chmod - change mode of a file 

SYNOPSIS 

integer function chmod (name, mode) 
character*(*) name, mode 

DESCRIPTION 

This function changes the filesystem mode of file name. Mode can be any 
specification recognized by chmod{\). Name must be a single pathname. 

The normal returned value is 0. Any other value will be a system error 
number. 

FILES 

/usr/lib/libU77.a 

/bin/chmod exec'ed to change the mode. 

SEE ALSO 

chmod(l) 

BUGS 

Pathnames can be no longer than MAXPATHLEN as defined in 

<syslparam.h>. 

ORIGIN 

MIPS Computer Systems | 
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NAME 

conjg, dconjg - FORTRAN complex conjugate intrinsic function 
SYNOPSIS 

complex cxl, cx2 

double complex dxl, dx2 

cx2 = conjg(cxl) 
dx2 = dconjg(dxl) 
DESCRIPTION 

conjg returns the complex conjugate of its complex argument dconjg 
returns the double-complex conjugate of its double-complex argument. 
ORIGIN 

MIPS Computer Systems 
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NAME 

cos, dcos, ccos, zcos, cosd, dcosd - FORTRAN cosine intrinsic function 

SYNOPSIS 

real rl 9 r2 

double precision dpi, dp2 ^- 

complex cxl, cx2 I 

complex* 16 cdl, cd2 v 

real*4 r3, r4 

real*8 dp3, dp4 

r2 = cos(rl) 

dp2 = dcos(dpl) 
dp2 = cos(dpl) 

cx2 = ccos(cxl) 
cx2 = cos(cxl) 

dp4 = zcos(dp3) 
dp4 = cos(dp3) 

r4 = cosd(r3) 

dp4 = dcosd(dp3) 
dp4 = cosd(dp3) 

DESCRIPTION 

cos returns the real cosine of its real argument dcos returns the double- 
precision cosine of its double-precision argument, ccos returns the com- 
plex cosine of its complex argument, zcos returns the complex* 16 cosine 
of its complex* 16 argument. The arguments for these routines must be in 
radians and is treated modulo 2P. The generic form cos may be used with 
impunity as its returned type is determined by that of its argument. 
cosd returns the real*4 cosine of its real*4 argument. The argument for 
cosd must be in degrees and is treated as modulo 360. dcosd returns the 
real*8 cosine of its real*8 argument. The generic form cosd may be used 
with impunity as its returned type is determined by that of its argument. 

SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

cosh, dcosh - FORTRAN hyperbolic cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = cosh(rl) 

dp2 = dcosh(dpl) 
dp2 = cosh(dpl) 

DESCRIPTION 

cosh returns the real hyperbolic cosine of its real argument, dcosh returns 
the double-precision hyperbolic cosine of its double-precision argument. 
The generic form cosh may be used to return the hyperbolic cosine in the 
type of its argument. 

SEE ALSO 

sinh(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

dim, ddim, idim, iidim, jidim - FORTRAN positive difference intrinsic 
functions 

SYNOPSIS 

real rl, r2, r3 double precision dpi, dp2, dp3 integer il, i2, i3 
integer*2 HI, ii2, ii3 integer*4 jil, ji2, ji3 f 

r3 = dim(rl, r2) 

dp3 = ddim(dpl, dp2) dp3 = dim(dpl, dp2) 

i3 = idim(il, i2) i3 = dim(il, i2) 

ii3 = iidim(iil, ii2) ii3 = idim(iil, ii2) ii3 = dim(iil, ii2) 

ji3 = jidim(jil, ji2) ji3 = idim(jil, ji2) ji3 = dim(jil, ji2) 

DESCRIPTION 

These functions return: 

argl-arg2 if argl > arg2 

ifargl<=arg2 

ORIGIN 

MIPS Computer Systems 
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NAME 

dprod - FORTRAN double precision product intrinsic function 

SYNOPSIS 

real al, a2 
double precision a3 

a3 = dprod(al, a2) 

DESCRIPTION 

dprod returns the double precision product of its real arguments. 
ORIGIN 

MIPS Computer Systems 



April 1990 -1- Version 3.0 



ETIME(3F) Silicon Graphics ETIME(3F) 



NAME 

etime, dtime - return elapsed execution time 

SYNOPSIS 

function etime (tarray) 
real tarray(2) 

function dtime (tarray) 
real tarray(2) 

DESCRIPTION 

These two routines return elapsed runtime in seconds for the calling pro- 
cess. Dtime returns the elapsed time since the last call to dtime, or the start 
of execution on the first call. 

The argument array returns user time in the first element and system time in 
the second element. The function value is the sum of user and system time. 

The resolution of all timing is 1/HZ. See the system include file param.h in 
lusrlincludelsys for the value of HZ. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

times(2) 

ORIGIN 

MIPS Computer Systems 
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NAME 

exp, dexp, cexp, zexp - FORTRAN exponential intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 
complex* 16 cdl, cd2 

r2 = exp(rl) 

dp2 = dexp(dpl) 
dp2 = exp(dpl) 

cx2 = cexp(cxl) 
cx2 = exp(cxl) 

cd2 = zexp(cdl) 
cd2 = exp(cdl) 

DESCRIPTION 

exp returns the real exponential function e x of its real argument, dexp 
returns the double-precision exponential function of its double-precision 
argument, cexp returns the complex exponential function of its complex 
argument, zexp returns the complex* 16 exponential function of its com- 
plex*^ argument. The generic function exp becomes a call to dexp, cexp 
or zexp as required, depending on the type of its argument. 

SEE ALSO 

exp(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

fdate - return date and time in an ASCII string 

SYNOPSIS 

subroutine fdate (string) 
character*(*) string 

character*(*) function fdateO 

DESCRIPTION 

Fdate returns the current date and time as a 24 character string in the format 
described under ctime(3). Neither 'newline' nor NULL will be included. 

Fdate can be called either as a function or as a subroutine. If called as a 
function, the calling routine must define its type and length. For example: 

character*24 fdate 
external fdate 

write(*,*) fdate() 



FILES 



/usr/lib/libU77.a 

SO 

ctime(3), time(3F), itime(3F), idate(3F), ltime(3F) 



SEE ALSO | 



ORIGIN 

MIPS Computer Systems 
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NAME 

fixade - FORTRAN misaligned data bus error handler and report generator 
SYNOPSIS 

subroutine handle_unaligned_traps 

subroutine listjbyaddr 
subroutine summary_listing 
subroutine printunalignedsummary 
DESCRIPTION 

Fixade is a FORTRAN bus error handler which fields, corrects, and reports 
bus errors arising due to misaligned data in FORTRAN programs. The 
MIPS architecture, for performance reasons, is very restrictive on the align- 
ment of data which can be used with its standard instruction set. Usually, 
the compilers can guarantee this alignment. In FORTRAN, however, some 
situations exist in which this guarantee cannot be made. These misalign- 
ments may be necessary to satisfy equivalence statements, due to 
mismatched formal/actual parameter types, or due to user-instructed 
suppression of common block padding (via use of the -align switches, see 
/77(1)). Unless the bus error arising due to a load or store from a 
misaligned address is caught, it will cause unexpected program failure. 
Routines in the fixade package provide a bus error handler to catch these 
errors, correct them, and allow the program to continue execution. They 
also provide a reporting facility so that the causes of these errors can be 
located and remedied. 

NOTE: the use of this trap handler is intended for diag- 
nostic purposes only. Program efficiency may be severly 
impacted by its use. 

None of the routines of fixade have arguments. The routine 
handle_unaligned_traps must be called to initialize the handler. If a 
misaligned reference is encountered prior to calling this initialization rou- 
tine, the reference will produce a core dump. No other routines of the trap 
handler may be called prior to calling this initialization routine. 

No other routines of the trap handler need to be called unless a report of 
misaligned references is desired. A report of misaligned references consists 
of two portions: a summary of the types of misaligned instructions, their 
counts and relative frequency, (e.g., 'half aligned load-word occurred 
fifteen times, and accounted for 2% of all misaligned references'); and a 
listing based either on the instruction addresses at which the faults occurred, 
or the data addresses producing the faults. 
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FILES 



/usr/lib/fixade.o 



AUTHOR 

Larry Weber 
Greg Boyd 
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This listing is either an exhaustive listing (default), or a summary listing. 
The summary listing will list the address (either instruction or data, as 
opted) associated with the fault, and its absolute and relative frequency, as a 
percentage. The exhaustive listing will list all instruction/data address pairs 
producing a fault. This listing will be sorted by the address on which the 
listing is based (i.e., by instruction address or data address). By default, the 
listing is exhaustive. If only a summary of misalignment errors is desired, 
the routine summary Jisting must be called immediately after the initiali- 
zation routine. 

Also by default, the listing is based on instruction addresses. If it is desired 
to base the listing on data addresses, the routine listjbyaddr must be 
invoked during initialization. 

Prior to program exit, the routine print_unaligned_summary may be 
called to print the listing of bus error events, in either summary or exhaus- 
tive format, as described previously. This listing will go to the standard 
output A sample line of this listing in summary format might be 

0x0042445c 1536 33% 67% 

where 0x0042445c is the address associated with 1536 faults (33% of the 
total). The final percentage is cumulative. Whether the address is of the 
data causing the fault or the instruction at which it occurred is indicated in a | 
printed heading. ^ 

New options have been added to/77(l) to generate (much slower) code 
which tolerates misalignments (see/77(l)). As discussed previously, use of 
these options will suppress the padding of common usually done by the for- 
tran compiler to align elements. They will also generate code which uses 
pessimistic code sequences to avoid bus errors due to misalignment. No 
bus errors due to misaligned data will occur in modules compiled with these 
new options. 

Users desiring to find and repair instances of misaligned data may use either 
instruction addresses to decide which modules need to be specially com- 
piled (seey77(l)), or data addresses to find misalignments. In either case, a 
symbol table listing produced by ww(l), using the -Bgn options, will be 
necessary to map the addresses to routine (or common block) names. 
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SEE ALSO 

f77(l) 

DIAGNOSTICS 

When making an exhaustive listing, the trap handler's tables may overflow. 
If this occurs, the message 

number events not listed due to insufficient table size. 

will be printed at the end of the listing. 

ORIGIN 

Silicon Graphics, Inc. 
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NAME 

fseek, ftell - reposition a file on a logical unit 

SYNOPSIS 

integer function fseek (limit, offset, from) 
integer offset, from 

integer function ftell (lunit) 

DESCRIPTION 

lunit must refer to an open logical unit, offset is an offset in bytes relative 
to the position specified by from. Valid values for from are: 



c 



FILES 



meaning 'beginning of the file* 

1 meaning 'the current position' 

2 meaning 'the end of the file' 

The value returned by fseek will be if successful, a system error code oth- 
erwise. (See/?err0r(3F)) 

Ftell returns the current position of the file associated with the specified log- 
ical unit. The value is an offset, in bytes, from the beginning of the file. If 
the value returned is negative, it indicates an error and will be the negation 
of the system error code. (See perror(3F)) 

c 

/usr/lib/libU77.a v 



SEE ALSO 

fseek(3S),perror(3F) 

ORIGIN 

MIPS Computer Systems 
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NAME 

handle_sigfpes - floating-point exception handler package 

SYNOPSIS 

#include <fsigfpe.h> 

subroutine 

handle^sigfpesConoffjenjmaskjUser^routinejabort^actionjabortroutine) 
integer *4 onoff, enjmask, abort_action 
integer *4 abort_routine, user_routine 
external abort_routine, user_routine 

structure /sigfpe_template/ 

integer * 4 repls 

integer * 4 count 

integer * 4 trace 

integer * 4 abort 

integer * 4 exit 

end structure 

record /sigfpejemplate/ fsigfpe (0:FPE_N_EXCEPTION TYPES) 

common / sigfpe / fsigfpe (0:FPEN EXCEPTION TYPES) 

integer * 4 resuIts(0:FPE NJNVALIDOPRESULTS) 
common / invalidop_results / results 

integer * 4 invop(0:FPE N JNVALIDOP_OPERANDS) 
common / invalidop_operands / invop 

DESCRIPTION 

The MIPS floating-point accelerator may raise floating-point exceptions due 
to five conditions: FPE_0\ERFL(overflow), 

FPEJJNDERFL(underflow), FFEJ)I\ZERO(divide-by-zero\ 

FPEJNEXACT(inexact result), or FPEJNVALID(mva//d operand, e.g., 
infinity). Usually these conditions are masked, and do not cause a floating- 
point exception. Instead, a default value is substituted for the result of the 
operation, and the program continues silently. This event may be inter- 
cepted by causing an exception to be raised. Once an exception is raised, 
the specific conditions which caused the exception may be determined, and 
more appropriate action taken. 

The library libfpe.a privides two methods to unmask and handle these con- 
ditions: the subrouitne handlesigfpes, and the environment variable 
TRAPJFPE. Both methods provide a mechanism for unmasking each con- 
dition except FPE_INEXACT, for handling and classifying exceptions 
arising from them, and for substituting either a default value or a chosen 
one. They also provide mechnisms to count, trace, exit or abort on enabled 
exceptions. The subroutine handlesigfpes will always override options set 
by the environment variable TRAPFPE. TRAP_FPE is supported for 
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Fortran, C and Pascal. Handle_sigfpes is supported for C and Fortran. 
Arguments to handlejsigfpes have the following interpretation: 

onoff is a flag indicating whether handling is being turned on (onoff == 
FPEON) or off (onoff == FPEOFF). Information from the sigfpe struc- 
ture will be printed if (onoff— FPEDEBUG). (defined in fsigfpe.h). 

enjnask indicates which of the four conditions should be unmasked, ena- 
bling them to raise floating-point exceptions, enjnask is only valid if onoff 
== FPE_ON, and is the sum of the constants FPE_EN_UNDERFL, 
FPEJENOVERFL, FPE_EN„DIVZERO, and FPE_EN_INVALID 
(defined in fsigfpe.h). 

userjoutine: handle_sigfpes provides a mechanism for setting the result 
of the operation to any one of a set of well-known values. If full control 
over the value of selected operations is desired for one or more exception 
conditions, a subroutine userjoutine must be provided. For these selected 
exception conditions, userjoutine will be called to set the value resulting 
from the operation. 

abort _action: If the handler encounters an unexpected condition, an incon- 
sistency, or begins looping, the flag abort action indicates what action 
should be taken. Legal values are: 



FPE TURN_OFF_HANDLER_ON_ERROR 



instruct the floating-point- 
accelerator to cease causing excep- 
tions and continue. (i.e., disable 
handling) 



FPE JU*ORT_ON_ERROR 



kill the process after giving an 
error message and possibly calling 
a user-supplied cleanup routine. 



FPE_REPLACEJIANDLER_ONJERROR 



install the indicated user routine as 
the handler when such an error is 
encountered. Future floating-point 
exceptions will branch to the user- 
routine, (see signal(2)) 



C 



( 



abort joutine: When a fatal error (i.e., one described under abort jiction 
above) is encountered, abort joutine is used as the address of a user sub- 
routine. If abort_action is FPE_ABORT_ON_ERROR, and abort joutine is 
valid, it is called before aborting, and passed a pointer to the address of the 
instruction causing the exception as its single argument (see below under 
DIAGNOSTICS). 



( 
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If abort_action is FPE_REPLACE_HANDLER_ON_ERROR, and 
abort joutine is valid, it will be installed as the new handler. In this case, 
the instruction which caused the unexpected exception will be re-executed, 
causing a new exception, and abort joutine entered, (see signal(2) for the 
correct interface for exception handlers) 

When an exception is encountered, the handler examines the instruction 
causing the exception, the state of the floating-point accelerator and the 
sigfpe structure to determine the correct action to take, and the program is 
continued. In the cases of FPEJJNDERFL, FPEOVERFL, 
FPEJMVZERO, and some instances of FPEJNVALID, an appropriate 
value is substituted for the result of the operation, and the instruction which 
caused the exception is skipped. For most exceptions arising due to an 
invalid operand (FPEJNVALID exceptions), more meaningful behavior 
may be obtained by replacing an erroneous operand. For these conditions, 
the operand is replaced, and the instruction re-issued. 

sigfpe: For each enabled exception, the sigfpe structure contains the fields: 
repls, count, trace, exit and abort. For each enabled exception <p>, and each 
non-zero entry <n> in the sigfpe structure, the trap handler will take the fol- 
lowing actions: 

count: A count of all enabled traps will be printed to stderr at the end of 
execution of the program , and every at <n>th exception <p>. 
trace: A dbx stack trace will be printed to stderr every exception <p>, up to 
<n> times. 

abort: Core dump and abort program upon encountering the <n>th excep- 
tion <p>. The abort option takes precedence over the exit option. 
exit: Exit program upon encountering the <n>th exception <p>. repls: 
Each of the exceptions JJNDERFL, _OVERFL, and JDIVZERO has an 
associated default value which is used as the result of the operation causing 
the exception. These default values may be overridden by initializing this 
integer value. This value is interpreted as an integer code used to select one 
of a set of replacement values, or to indicate that the routine user joutine is 
responsible for setting the value. 
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These integer codes are listed below: 

FPE_ZERO use zero as the replacement value 



FPE_MIN 



FPE_MAX 



FPE INF 



FPE NAN 



FPE APPROPRIATE 



FPE_USER_DETERMINED 



use the appropriately -typed 
minimum value as the replacement, 
(i.e., the smallest number which is 
representable in that format without 
denormalizing) 

use the appropriately-typed max- 
imum value as the replacement 
use the appropriately -typed value 
for infinity as the replacement 
use the appropriately -typed value 
for not-a-number as the replace- 
ment. (A quiet not-a-number is 
used.) 

use a handler-supplied appropriate 
value as the replacement. These 
are different from the default 
values: FPE_ZERO for 
FPEJUNDERFL, FPE.MAX for 
FPEJWERFL, FPEJNF for 
FPE JMVZERO. Values for 
FPEJN VALID are handled on a 
case-by -case basis, 
invoke the routine userjoutine 
(see note) to set the value of the 
operation. If this is the code used 
for FPE INVALID exceptions, all 
such exceptions will defer to 
userjoutine to set their value. In 
this case, invalidop _results _ and 
invalidop _operands _ will be 
ignored. 



C 



( 



( 
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The default values used as the results of floating-point exceptions are: 



values for fsigfpe().repls 



element 
# mnemonic 



(none) 

1 FPEJLJNDERFL 

2 FPE_OVERFL 

3 FPE_DIVZERO 

4 FPEJNVALED 



exception condition 



(ignored) 
underflow 
overflow 
divide-by-zero 
invalid operand 



default value 



FPEJVHN 
FPE_MAX 
FPE_MAX 
FPE_APPROPRIATE 



For FPE_INVALID exceptions, the correct action may be either to set the 
result and skip the instruction, or to replace an operand and retry the 
instruction. There are four cases in which the result is set. The integer array 
constituting the named common invalidopjesults is consulted for replace- 
ment codes for these cases: 





array in common block invt 
element 


ilidop_results 




# 


mnemonic 


exception condition 


default value 




1 

2 
3 
4 


(none) 

FPE^.MAGNITUDE_INF_SUBniACTION 

FPE_ZERO_TIMES_INF 

FPE_ZEROJDIV_ZERO 

FPEJNFJDIVJNF 


(ignored) 

oo — oo 
0*oo 

0/0 

oo / oo 


FPE_INF 
FPE_ZERO 
FPE_ZERO 
FPEJNF 



There are six cases in which an offending operand is replaced. An integer 
array constituting the named common invalidop_operands is consulted for 
user-initialized codes for these cases. 
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Each element governs the following cases: 



NOTE 





array in common 


block invalidop_operands 




element 






# 


mnemonic 


exception condition 


default value 





(none) 


(ignored) 


(none) 


1 


FPE_SQRT_NEG_X 


sqrt(-x) 


(currently not sup- 
ported) 


2 


FPE_CVT_OVERFL 


conversion to real 
caused target to 
overflow 


FPE.MAX 


3 


FPE_TRUNK_OVERFL 


conversion to integer 
caused target to 
overflow 


FPE_MAX 


4 


FPE_CVT_NAN 


conversion of NaN 


FPEJMAX 


5 


FPE.CVTJNF 


conversion of <» 


FPE_MAX 


6 


FPE_UNORDERED,CMP 


comparison to NaN 


FPEJMAX 


7 


FPE_SNAN_OP 


operand was Signal- 
ing Nan 


FPEJMAX 



c 



Use of userjoutine to set values 

If the integer code defining the replacement value for a particular exception 
condition is FPE_USERJ)EFINED, the user-supplied routine userjoutine 
is called: 

call user_routine(exception parameters, value) 

value is an integer * 4 array of length two into which userjoutine should 
store the replacement value. 



( 



( 
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exception_parameters is a zero-based integer * 4 array of length five which 
describes the exception condition: 



element 
mnemonic 



array exception parameters 



description 



FPE_EXCEPTION_TYPE 

1 FPEJNVALID_ACTION 



2 FPE_INVALID_TYPE 



FPE.VALUE TYPE 



FPE VALUE SIGN 



the exception type (FPE_DIVZERO, etc), 
value = FPE_SET_RESULT if result is 
being set. Otherwise, an operand is being 
replaced. This element is meaningful 
only if the exception type is 
FPEJNVALID. 

This element is meaningful only if the 
exception type is FPEJNVALID It is 
the index corresponding to the particular 
conditions giving rise to the exception. 
In conjunction with element 1, this value 
uniquely determines the exception condi- 
tion. (e.g., if FPE_INVAIJD_ACTION 
is FPE_SET_RESULT and 
FPEJNVAUDTYPE is 2, the 
FPEJNVALID exception is due to 
FPE_ZERO_TMESJNF.) 
the type of the replacement value - either 
FPE_SINGLE, FPEJDOUBLE or 
FPE_WORD. 

the suggested sign userjrouiine should 
use for the replacement value - either 
FPE.POSriTVE or FPE_NEGATTVE. 



The environment variable TRAPJFPE: 

If the code has been compiled with libfpe.a, the runtime startup routine will 
check for the environment variable "TRAPFPE". The string read as the 
value of TRAPFPE will be interpreted and handle_sigfpes will be called 
with the resulting values. If the program contains an explicit call to 
handle_sigfpes, that call will override all actions defined by TRAPFPE. 

TRAPFPE is read in upper case letters only. The string assigned to 
TRAPFPE may be in upper case or lower case. TRAPFPE can take one 
of two forms: either a global value, or a list of individual items. 
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global values: 

"" or OFF Execute the program with no trap handling 
enabled. Same as TRAP_FPE undefined. 
Same as linking without libfpe.a 
ON SameasTRAP_FPE="ALL=DEFAULT". 

Alternately, replacement values and actions may be specified for each of the 
possible trap types individually. This is accomplished by setting the 
environment variable as follows: 

setenv TRAPJFPE "item;item;item.... M 

an item can be one of the following: 

traptype=statuslist Where traptype defines the specific 
floating point exception to enable, 
and statuslist defines the list of 
actions upon encountering the trap. 

DEBUG Confirm the parsing of the environ- 

ment variable, and the trap actions. 

Traptype can be one of the following literal strings: 

UNDERFL underflow 

OVERFL overflow 

DIVZERO divide by zero 

INVALID invalid operand 

ALL all of the above 

Statuslist is a list seperated by commas. It contains an optional symbolic 
replacement value, and an optional list of actions. 

symbolic replacement values: 

DEFAULT Do not override the predefined default values. 

IEEE Maps to integer code ..APPROPRIATE. 

ZERO Maps to integer code _ZERO. 

MIN Maps to integer code _MIN. 

MAX Maps to integer code _M AX. 

INF Maps to integer code _INF. ' 

NAN Maps to integer code _NAN. I 



( 
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All actions take an optional integer in parentheses: 

Note: for any traps that have an action and no specified replacement value, 
the DEFAULT replacement value will be used. 

COUNT(n) A count of the trap type will be 

printed to stderr every nth trap, and 

at the end of the program. Default 

is MAXINT. 
ABORT(n) Core dump and abort the program 

upon encountering the nth trap. 

Default id 1. 
EXIT(n) Exit program upon encountering 

the nth trap. Default id 1 . 
TRACE(n) If a trap is encountered, Print a 

stack trace to stderr up to n times. 

Default is 10. 



EXAMPLE 

setenv TRAP FPE "ALL=COUNT; UNDERFL=ZERO* 

OVERFL=IEEE,TRACE(5), ABORT(IOO); DIVZEROABORT" 

Count all traps, trace the first five overflows, abort on the first divide by 
zero, or the 100th overflow. Replace zero for underflows, the "appropriate" 
value for overflows, and the default values for divide by zero, and invalid 
operands. 

SEE ALSO 

signal(3c), sigfpe(3c) 

DIAGNOSTICS 

If the handler encounters an unexpected condition, an inconsistency, or 
begins looping, the flag abortjxction and subroutine address abort joutine 
(parameters to handle_sigfpes) indicate what action should be taken. If 
abort_action is FPE_ABORT_ON_ERROR, the handler will be removed 
leaving the exceptions enabled, an error message printed, and the instruc- 
tion causing the fault re-issued, giving a core dump. Prior to this, if 
abort routine is valid, it is invoked as 

call abort_routine(ptr_to_pc) 

where ptr_to_pc is an integer * 4 parameter whose value is the address of 
the instruction which caused the exception. 
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If abortjxction is FPE_REPLACE_HANDLER_ON_ERROR, and 
abort joutine is valid, handle_sigfpes removes its handler and installs 
abort joutine as the new handler. The instruction which caused the excep- 
tion will be re-executed, causing a new exception, and abort joutine 
entered, (see signal(2)) ^ 

If abortjxction is FPE_TURN_OFF^HANDLER_ON_ERROR (^ 
handle jrfgfpes will mask (disable) floating-point exceptions and remove 
its handler. The instruction which caused the fault will then be re-issued, 
continuing the program as if floating-point exceptions had never been 
enabled. 

Any other combination of the two parameters abort jction and 
abort joutine will cause handle jiigf pes to remove its handler, generate an 
error message, and re-issue the instruction causing the exception, producing 
a core dump. 



c 
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NAME 

ftype: int, ifix, iifix, jifix, idint, real, float, floati, floatj, sngl, dble, dfloti, 
dflotj, dfloat, cmplx, dcmplx, ichar, char - explicit FORTRAN type conver- 
sion 

SYNOPSIS 

integer i, j 

real r, s 

double precision dp, dq 

complex ex, cy, cz 

double complex dcx, dcy, dcz 

character*/ ch 

integer*2 ii 

integer*4 ji 

real*4 rl 

real*8 dpi 

i = intO) 
i = int(r) 
i = int(dp) 
i = int(cx) 
i = ifix(r) 
ii = iifix(rl) 
ji = jifix(rl) 
i = idint(dp) 
i = idint(cx) 

r = real(i) 
r = real(dp) 
r = real(cx) 
r = real(s) 
r = float(i) 
rl = floati(ii) 
rl = floatJO'i) 
r = sngl(dp) 
r = sngl(cx) 
r = sngl(s) 

dp = dble(i) 
dp = dble(r) 
dp = dble(dq) 
dp = dble(cx) 
dp = dfloat(r) 
dp = dfloat(dp) 
dp = dfloat(cx) 
dpi = dfloti(ii) 
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dpi = dflotjCji) 

ex = cmplx(i) 

ex = cmplx(i, j) 

ex = cmplx(r) 

ex = cmplx(r, s) ^ 

ex = cmplx(dp) I 

ex = cmplx(dp, dq) ^ 

ex = cmplx(cy) 

ex = cmplx(cy, cz) 

ex = cmplx(dcx) 

ex = cmplx(dcx, dcy) 

dcx = dcmplx(i) 
dcx = demplx(i, j) 
dcx = dcmplx(r) 
dcx = dcmplx(r, s) 
dcx = dcmplx(dp) 
dcx = dcmplx(dp, dq) 
dcx = dcmplx(cx) 
dcx = dcmp!x(cx, cy) 
dcx = dcmplx(dcy) 
dcx = dcmplx(dcy, dcz) 

i = ichar(ch) 
eh = char(i) 

DESCRIPTION 

These functions perform conversion from one data type to another. 

The function int converts to integer form its real, integer, real*4 9 double 
precision, or complex argument If the argument is real, integer, real*4, or 
double precision, int returns the integer whose magnitude is the largest 
integer that does not exceed the magnitude of the argument and whose sign 
is the same as the sign of the argument (i.e. truncation). For complex the 
above rule is applied to the real part, ifix converts only real arguments, int 
and ifix return result type integer*2 if the 42 option is in effect; otherwise, 
the result type is integer*4. iifix and jifix convert only realH to integer*! 
and integer*4, respectively, idint converts double precision and complex 
arguments only. 

The function real converts to real form an integer, integer*2, integer*4, 
real, double precision, or complex argument. If the argument is double pre- f 
cision, as much precision is kept as is possible. If the argument is complex, \ 
the real part is returned, float converts integer arguments only, floati and 
floatj convert integer*2 and integerH arguments respectively to real*4. 
sngl converts double, complex and real arguments to real. 
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The function dble converts any integer, real, double, complex, integer*2 or 
integer*4 argument to double precision form. If the argument is complex, 
the real part is returned, dfloat converts real, double, and complex to dou- 
ble, dfloti and dflotj convert integer*2 and integerH to real*8. 

The function cmplx converts its integer, real, double precision, or double 
complex arguments) to complex form. 

The function dcmplx converts to double complex form its integer, real, 
double precision, or complex argument(s). 

Either one or two arguments may be supplied to cmplx and dcmplx . If 
there is only one argument, it is taken as the real part of the complex type 
and an imaginary part of zero is supplied. If two arguments arc supplied, the 
first is taken as the real part and the second as the imaginary part. 

The function ichar converts from a character to an integer depending on 
the character's position in the collating sequence, ichar returns the result 
type integer*2 if the -i2 compile option is in effect; otherwise the result 
type is integer*4. 

The function char returns the character in the zth position in the processor 
collating sequence where / is the supplied argument. 

ORIGIN 

MIPS Computer Systems 
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NAME 

getarg, iargc - return Fortran command-line argument 

SYNOPSIS 

character*N c 

integer i, j ^- 

integer function iargc I 

call getarg(i 9 c) 
j = iargcO 

DESCRIPTION 

getarg returns the i-th command-line argument of the current process. 

iargc returns the index of the last argument. 

foo argl arg2 arg3 
getarg(2 t c) would return the string "arg2" in the character variable c. 
iargc would return 3 as the value of the function call. 

SEE ALSO 

getopt(3C). 

NOTES 

The compiler expects the existence of a Fortran MAIN_ program when 
these functions are used. f 

ORIGIN 

AT&TV.3 
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NAME 

getc, fgetc - get a character from a logical unit 

SYNOPSIS 

integer function getc (char) 
character char 

integer function fgetc (lunit, char) 
character char 

DESCRIPTION 

These routines return the next character from a file associated with a fortran 
logical unit, bypassing normal fortran I/O. Getc reads from logical unit 5, 
normally connected to the control terminal input. 

The value of each function is a system status code. Zero indicates no error 
occurred on the read; -1 indicates end of file was detected. A positive 
value will be either a UNIX system error code or an f77 I/O error code. See 
perror(3F). 

BUGS 

fgetc(3f) does not work for FORTRAN unit numbers other than 5. 
FILES 

/usr/lib/UbU77.a 

SEE ALSO 

getc(3S), intro(2), perror(3F) 

ORIGIN 

MIPS Computer Systems 
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NAME 

getenv - get value of environment variable 

SYNOPSIS 

subroutine getenv( ename, evalue ) 

character *(*) ename, evalue ^ 

DESCRIPTION V. 

getenv returns the character-string value of the environment variable 
represented by its first argument into the character variable of its second 
argument. If no such environment variable exists, all blanks will be 
returned. 

SEE ALSO 

getenv(3C), environ(5). 

ORIGIN 

AT&TV.3 



( 



( 



April 1990 -1- Version 3.0 



GETLOG(3F) Silicon Graphics GETLOG(3F) 

NAME 

getlog - get user's login name 

SYNOPSIS 

subroutine getlog (name) 
character*(*) name 

character*(*) function getlogO 
DESCRIPTION 

Getlog will return the user's login name or all blanks if the process is run- 
ning detached from a terminal. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

getlogin(3) 

ORIGIN 

MIPS Computer Systems 
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NAME 

idate, itime - return date or time in numerical form 

SYNOPSIS 

subroutine idate (imon,iday,iyear) 
integer imon,iday,iyear 

subroutine itime (iarray) 
integer iarray(3) 

DESCRIPTION 

Idate returns the current date in the variables imon, iday, and iyear. The 
order is: mon, day, year. Month will be in the range 1-12. Year will be 
returned as the last two digits. 
Itime returns the current time in iarray. The order is: hour, minute, second. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

ctime(3F), fdate(3F) 

ORIGIN 

MIPS Computer Systems 



( 



( 



( 



April 1990 



. 1 » Version 3.0 



IMAG(3F) Silicon Graphics IMAG(3F) 

NAME 

imag, aimag, dimag - FORTRAN imaginary part of complex argument 
SYNOPSIS 

real r 

complex cxr 

double precision dp 

double complex cxd 

r = aimag(cxr) 
r = imag(cxr) 

dp = dimag(cxd) 
dp = imag(cxd) 

DESCRIPTION 

aimag returns the imaginary part of its single-precision complex argument. 
dimag returns the double-precision imaginary part of its double-complex 
argument. The generic form imag may be used with impunity as its argu- 
ment will determine the type of the returned value. 

ORIGIN 

MIPS Computer Systems 
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NAME 

index - return location of FORTRAN substring 

SYNOPSIS 

character*Nl chl 

character*N2 ch2 ^ 

integer i I 

i = index(chl, ch2) 

DESCRIPTION 

The result of index is an integer value indicating the position in the first 
argument of the first substring which is identical to the second argument. 
The result of index(' ABCDEF' , 'CD'), for example, would be 3. If no sub- 
string of the first argument matches the second argument, the result is zero. 
index returns the result type integer*2 if the -i2 compile option is in effect; 
otherwise, the result type is integer*4. 

ORIGIN 

MIPS Computer Systems 



c 
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NAME 

len - return length of Fortran string 

SYNOPSIS 

character*N ch 
integer i 

i = len(ch) 

DESCRIPTION 

len returns the length of string ch . 

ORIGIN 

MIPS Computer Systems 
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NAME 

loc - return the address of an object 

SYNOPSIS 

function loc(arg) 

DESCRIPTION 

The returned value will be the address of org. 

FILES 

/usr/lib/libU77.a 

ORIGIN 

MIPS Computer Systems 



c 



c 



( 



April 1990 



- 1 - Version 3.0 



LOG(3F) Silicon Graphics LOG(3F) 

NAME 

log, alog, dlog, clog, zlog - FORTRAN natural logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 
complex* 16 cdl, cd2 

r2 = alog(rl) 
r2 = log(rl) 

dp2 = dlog(dpl) 
dp2 = log(dpl) 

cx2 = clog(cxl) 
cx2 = log(cxl) 

cd2 = zlog(cdl) 
cd2 = log(cdl) 

DESCRIPTION 

alog returns the real natural logarithm of its real argument, dlog returns the 
double-precision natural logarithm of its double-precision argument. The 
argument of alog and dlog must be greater than zero, clog returns the com- 
plex logarithm of its complex argument. The argument of clog must not be 
(0.,0.). The range of the imaginary part of clog is: -p < imaginary part <= 
p. zlog returns the complex* 16 logarithm of its complex* 16 argument. 
The generic function log becomes a call to alog, dlog, clog, or zlog 
depending on the type of its argument. 

SEE ALSO 

exp(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

loglO, aloglO, dloglO - FORTRAN common logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = aloglO(rl) | 

r2 = loglO(rl) V 

dp2 = dloglO(dpl) 
dp2 = loglO(dpl) 

DESCRIPTION 

aloglO returns the real common logarithm of its real argument. dloglO 
returns the double-precision common logarithm of its double-precision 
argument. The absolute value of the argument for aloglO and dloglO must 
be greater than zero. The generic function log 10 becomes a call to aloglO 
or dlogl depending on the type of its argument. 

SEE ALSO 

exp(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

malloc, free - main memory allocator 

SYNOPSIS 

pointer ptr 

ptr = malloc(nbytes) 

call free(ptr) 

DESCRIPTION 

malloc and free provide a simple general-purpose memory allocation pack- 
age, malloc returns a pointer to a block of at least nbytes bytes suitably 
aligned for any use. 

The argument to free is a pointer to a block previously allocated by malloc; 
after free is performed this space is made available for further allocation, 
but its contents are left undisturbed. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free, 

malloc allocates the first big enough contiguous reach of free space found 
in a circular search from the last block allocated or freed, coalescing adja- 
cent free blocks as it searches. It calls sbrk [see brk{2)] to get more 
memory from the system when there is no suitable space already free. 

DIAGNOSTICS 

malloc, returns a NULL pointer if there is no available memory or if the 
arena has been detectably corrupted by storing outside the bounds of a 
block. When this happens the block pointed to by ptr may be destroyed. 

NOTES 

Search time increases when many objects have been allocated; that is, if a 
program allocates but never frees, then each successive allocation takes 
longer. 
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NAME 

max, maxO, imaxO, jmaxO, amaxO, maxl, amaxl, dmaxl, imaxl, jmaxl, 
aimaxO, ajmaxO - FORTRAN maximum-value functions 

SYNOPSIS 

integer i 9 j, k, 1 

integer*2 iil, ii2, ii3 9 ii4 | 

integer*4 jil, ji2, ji3, ji4 V 

real a 9 b 9 c, d 

real*4 rl, r2, r3, r4 

double precision dpi, dp2 9 dp3 

k = maxO(i 9 j) 
1 = max(i, j, k) 

ii4 = imaxO(iil, ii2, ii3) 
ii4 = max(iil 9 ii2 9 ii3) 
ii3 = maxO(iil, ii2) 

ji4 = jmax0(jil 9 ji2, ji3) 

ji3 = max(jil, ji2) 

ji4 = maxO(jil, ji2, ji3) 

a = amaxO(i, j, k) 
a = max(i, j, k) 

i = maxl(a 9 b) 
i = max(a, b, c) 

d = amaxl(a, b, c) 
c = max(a, b) 

dp3 = dmaxl(dpl ? dp2) 
dp4 = max(dpl 9 dp2, dp3) 

iil = imaxl(rl 9 r2) 
iil = maxl(rl 9 r2, r3) 

jil = jmaxl(rl 9 r2) 
jil = maxl(rl, r2, r3) 

rl = aimaxO(iil, ii2, ii3) 
rl = amaxO(iil 9 ii2, ii3) 

rl = aimaxO(jil 9 ji2 9 ji3) 
rl = amaxO(jil, ji2 9 ji3) 

DESCRIPTION 

The maximum-value functions return the largest of their arguments. There 
may be any number of arguments, but they must all be of the same type. 
maxO returns the integer form of the maximum value of its integer 
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arguments; amaxO, the real form of its integer arguments; maxl , the integer 
form of its real arguments; amaxl , the real form of its real arguments; 
dmaxl, the double-precision form of its double-precision arguments; 
imaxl , the integer*2 form of its real*4 arguments; jmaxl , the integer*4 
form of its real*4 arguments; aimaxO, the real*4 form of its integer*2 argu- 
ments; and ajmaxO, the real*4 form of its integer*4 arguments, max, maxO, 
maxl , and amaxO are the generic forms which can be used as indicated 
above. 

SEE ALSO 

min(3F). 

ORIGIN 

MIPS Computer Systems 
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NAME 

mclock - return Fortran time accounting 

SYNOPSIS 

integer i 

i = mclock( ) f 

DESCRIPTION V. 

mclock returns time accounting information about the current process and 
its child processes. The value returned is the sum of the current process's 
user time and the user and system times of all child processes. 

SEE ALSO 

times(2), clock(3C), system(3F). 

ORIGIN 

AT&TV.3 
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NAME 

min, minO, iminO, jminO, aminO, mini, aminl, dminl, iminl, jminl, aiminO, 
ajminO - FORTRAN minimum-value functions 

SYNOPSIS 

integer i, j, k, I 

integer*2 iil, ii2, ii3, ii4 

integer*4 jil, ji2, ji3, ji4 

real a, b, c, d 

real*4 rl, r2, r3, r4 

double precision dpi, dp2, dp3 

k = minO(i, j) 
1 = min(i, j, k) 

ii4 = iminO(iil, ii2, ii3) 
ii4 = min(iil, ii2, ii3) 
ii3 = minO(iil, ii2) 

ji4 = jminO(jil, ji2, ji3) 

ji3 = min(jil, ji2) 

ji4 = minO(jil, ji2, ji3) 

a = aminO(i, j, k) 
a = min(i, j, k) 

i = minl(a 9 b) 
i = min(a, b, c) 

d = aminl(a, b, c) 
c = min(a, b) 

dp3 = dminl(dpl, dp2) 
dp4 = min(dpl, dp2, dp3) 

iil = iminl(rl, r2) 
iil = minl(rl, r2, r3) 

jil = jminl(rl, r2) 
jil = minl(rl, r2, r3) 

rl = aiminO(iil, ii2, ii3) 
rl = aminO(iil, ii2, ii3) 

rl = aiminO(jil, ji2, ji3) 
rl = aminO(jil, ji2, ji3) 

DESCRIPTION 

The minimum-value functions return the minimum of their arguments. 
There may be any number of arguments, but they must all be of the same 
type. minO returns the integer form of the minimum value of its integer 
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arguments; arninO, the real form of its integer arguments; mini , the integer 
form of its real arguments; aminl, the real form of its real arguments; 
dminl , the double-precision form of its double-precision arguments; iminl , 
the integer*2 form of its real*4 arguments; jminl , the integer*4 form of its 
real*4 arguments; aiminO, the real*4 form of its integer*2 arguments; and 
ajminO, the real*4 form of its integer*4 arguments. min> minO, mini , and ^r 
aminO are the generic forms which can be used as indicated above. I 

SEE ALSO 

max(3F). 

ORIGIN 

MIPS Computer Systems 
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NAME 

mod, imod, jmod, amod, dmod - FORTRAN remaindering intrinsic func- 
tions 

SYNOPSIS 

integer i, j, k 

integer*2 01, ii2, ii3 

integer*4 jil, ji2, ji3 

real rl, r2, r3 

double precision dpi, dp2, dp3 

k = mod(i, j) 

ii3 = imod(iil, ii2) 
ii3 = mod(iil, ii2) 

ji3 = jmod(jil, ji2) 
ji3 = mod(jil, ji2) 

r3 = amod(rl, r2) 
r3 = mod(rl, r2) 

dp3 = dmod (dp I, dp2) 
dp3 = mod(dpl, dp2) 

DESCRIPTION 

mod returns the integer remainder of its first argument divided by its second 
argument, imod returns the integer*2 remainder of its two integer*2 argu- 
ments, jmod returns the integer*4 remainder of its two integer*4 argu- 
ments, amod and dmod return, respectively, the real and double-precision 
whole number remainder of the integer division of their two arguments. 
The generic version mod will return the data type of its arguments. The 
result of these intrinsics is undefined when the value of the second argu- 



ment is zero. 



ORIGIN 



MIPS Computer Systems 
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NAME 

mp: mp J)lock, mp_blocktime, mp_create, mp_destroy, mp_my_ i threadnum, 
mp__numthreads, mp_set_numthreads, mp_setup, mp_unblock - FOR- 
TRAN multiprocessing utility routines 

SYNOPSIS 

subroutine mpJblockO f 

subroutine mpunblockQ 

subroutine mpjblocktime(iters) 
integer iters 

subroutine mpsetupO 

subroutine mp_create(num) 
integer num 

subroutine mpdestroyO 

integer function mp jiumthreads() 

subroutine mp_setjnumthreads(num) ^ 

integer num I 

integer function mp_my_threadnumO 

DESCRIPTION 

These routines give some measure of control over the parallelism used in 

FORTRAN jobs. They should not be needed by most users, but will help to 

tune specific applications. 

rnpjflock puts all slave threads to sleep via blockproc{2). This frees the 

processors for use by other jobs. This is useful if it is known that the slaves 

will not be needed for some time, and the machine is being shared by 

several users. Calls to mpjblock may not be nested; a warning is issued if 

an attempt to do so is made. 

mpjinblock wakes up the slave threads that were previously blocked via 

mp block. It is an error to unblock threads that are not currently blocked; a 

warning is issued if an attempt is made to do so. 

It is not necessary to explicitly call mpjinblock. When a FORTRAN paral- 
lel region is entered, a check is made, and if the slaves are currently 
blocked, a call is made to mpjinblock automatically. 
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mpjhlocktime controls the amount of time a slave thread waits for work 
before giving up. When enough time has elapsed, the slave thread blocks 
itself. This automatic blocking is independent of the user level blocking 
provided by the mpjblock/mpjunhlock calls. Slave threads that have 
blocked themselves will be automatically unblocked upon entering a paral- 
lel region. The argument to mpjblocktime is the number of times to spin in 
the wait loop. By default, it is set to 10,000,000. This takes about 3 
seconds on a 16MHz processor. As a special case, an argument of dis- 
ables the automatic blocking, and the slaves will spin wait without limit. 
The environment variable MPBLOCKTIME may be set to an integer value. 
It acts like an implicit call to mpjblocktime during program startup. 

mpjdestroy deletes the slave threads. They are stopped by forcing them to 
call exit(2). In general, doing this is discouraged, mpjblock can be used in 
most cases. 

mpjcreate creates and initializes threads. It creates enough threads so that 
the total number is equal to the argument. Since the calling thread already 
counts as one, mpjcreate will create one less than its argument in new slave 
threads. 

mpjetup also creates and initializes threads. It takes no arguments. It sim- 
ply calls mpjcreate using the current default number of threads. Normally 
the default number is equal to the number of cpu's currently on the 
machine. If the user has not called either of the thread creation routines 
already, then mpjetup is invoked automatically when the first parallel 
region is entered. If the environment variable MP SETUP is set, then 
mpjetup is called during FORTRAN initialization, before any user code is 
executed. 

mpjiumthreads returns the number of threads that would participate in an 
immediately following parallel region. If the threads have already been 
created, then it returns the current number of threads. If the threads have 
not been created, then it returns the current default number of threads. 
Knowing this can be useful in optimizing certain kinds of parallel loops by 
hand. 

mpjetjiumthreads sets the current default number of threads to the 
specified value. Note that this call does not directly create the threads, it 
only specifies the number that a subsequent mpjetup call should use. If the 
environment variable MP SET NUMTHREADS is set to an integer value, it 
acts like an implicit call to mpjetjiumthreads during program startup. For 
compatibility with earlier releases, NUMTHREADS is supported as a 
synonym for MP SET NUMTHREADS. 
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mpjnyjhreadnum returns an integer between and nA where n is the 
value returned by mpjtwnthreads. The master process is always thread 0. 
This is occasionally useful for optimizing certain kinds of loops by hand. 

SEE ALSO 

FORTRAN 77 Programmer' s Guide 

ORIGIN |^ 

Silicon Graphics, Inc. 
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NAME 

perror, gerror, ierrno - get system error messages 

SYNOPSIS 

subroutine perror (string) 
character*(*) string 

subroutine gerror (string) 
character*(*) string 

character* (*) function gerror() 

function ierrnoO 
DESCRIPTION 

Perror will write a message to fortran logical unit appropriate to the last 
detected system error. String will be written preceding the standard error 
message. 

Gerror returns the system error message in character variable string. Ger- 
ror may be called either as a subroutine or as a function. 

Ierrno will return the error number of the last detected system error. This 
number is updated only when an error actually occurs. Most routines and 
I/O statements that might generate such errors return an error code after the 
call; that value is a more reliable indicator of what caused the error condi- 
tion. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

intro(2), perror(3) 

D. L. Wasley, Introduction to the pi HO Library 



BUGS 



String in the call to perror can be no longer than 127 characters. 

The length of the string returned by gerror is determined by the calling pro- 
gram. 



NOTES 



UNIX system error codes are described in intro(2). The f77 I/O error codes 
and their meanings are: 

100 ' 'error in format' ' 

101 ' 'illegal unit number' ' 

102 ' 'formatted i/o not allowed' ' 
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103 "unformatted i/o not allowed' ' 

104 * 'direct i/o not allowed' ' 

105 "sequential i/o not allowed' ' 

106 "can't backspace file" 

107 "off beginning of record" 

108 "can't stat file" r 

109 "no * after repeat count' ' \^ 

110 "off end of record" 

111 " truncation failed' ' 

1 12 "incomprehensible list input" 

113 "out of free space" 

1 14 ' 'unit not connected' ' 

115 ' 'invalid data for integer format term' ' 

1 16 "invalid data for logical format term" 

117 "'new' file exists" 

118 "can't find 'old' file" 

1 19 ' 'opening too many files or unknown system error' ' 

120 * 'requires seek ability' ' 

121 ' 'illegal argument' ' 

122 "negative repeat count" 

123 "illegal operation for unit' ' 

124 "off beginning of record" 

125 "no * after repeat count" i 

126 "'new' file exists" V 

127 "can't find 'old' file" 

128 "unknown system error" 

129 ' 'requires seek ability' ' 

130 "illegal argument" 

131 "duplicate key value on write" 

132 "indexed file not open" 

133 ' 'bad isam argument' ' 

134 "bad key description" 

135 "too many open indexed files" 

136 "corrupted isam file" 

137 ' 'isam file not opened for exclusive access' ' 

138 "record locked" 

139 ' 'key already exists' ' 

140 "cannot delete primary key" 

141 "beginning or end of file reached" g 

142 "cannot find requested record" I 

143 ' 'current record not defined' ' 

144 ' 'isam file is exclusively locked' ' 

145 ' 'filename too long' ' 
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146 ' 'cannot create lock file' ' 

147 "record too long" 

148 ' 'key structure does not match file structure' ' 

149 ' 'direct access on an indexed file not allowed' ' 

1 50 ' 'keyed access on a f77sequential file not allowed' ' 

151 ' 'keyed access on a relative file not allowed' ' 

1 52 ' 'append access on an indexed file not allowed' ' 

153 "must specify record length" 

1 54 ' 'key field value type does not match key type" 

155 ' 'character key field value length too long' ' 

1 56 ' 'fixed record on f77sequential file not allowed' ' 

157 "variable records allowed only on unformatted 
f77sequential file" 

158 "stream records allowed only on f77formatted 
f77sequential file" 

159 "maximum number of records in direct access file 
exceeded" 

160 ' 'attempt to write to a readonly file' ' 

161 ' 'must specify key descriptions' ' 

162 ' 'carriage control not allowed for unformatted units' ' 

163 "indexed files only" 

164 ' 'cannot use on indexed file" 

165 ' 'cannot use on indexed or append file' ' 



ORIGIN 



MIPS Computer Systems 
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NAME 

putc, fputc - write a character to a fortran logical unit 

SYNOPSIS 

integer function putc (char) 
character char 

integer function fputc (lunit, char) 
character char 

DESCRIPTION 

These funtions write a character to the file associated with a fortran logical 
unit bypassing normal fortran I/O. Putc writes to logical unit 6, normally 
connected to the control terminal output. 

The value of each function will be zero unless some error occurred; a sys- 
tem error code otherwise. Seeperror(3F). 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

putc(3S), intro(2), perror(3F) 

ORIGIN 

MIPS Computer Systems 
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NAME 

putenv - change or add Fortran environment variable 
SYNOPSIS 

integer function putenv (string) 

character *(*) string 

DESCRIPTION 

String contains a character string in the form name-value. Putenv makes 
the value of the environment variable name equal to value by altering or 
creating an environment variable. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

putenv(3C) 

ORIGIN 

AT&TV.3 
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NAME 

qsort - quick sort 

SYNOPSIS 

subroutine qsort (array, len, isize, compar) 

external compar 

integer*2 compar | 

DESCRIPTION 

One dimensional array contains the elements to be sorted, len is the 
number of elements in the array, isize is the size of an element, typically - 

4 for integer and real 

8 for double precision or complex 

16 for double complex 

(length of character object) for character arrays 

Compar is the name of a user supplied integer*2 function that will deter- 
mine the sorting order. This function will be called with 2 arguments that 
will be elements of array. The function must return - 

negative if arg 1 is considered to precede arg 2 

zero if arg 1 is equivalent to arg 2 

positive if arg 1 is considered to follow arg 2 f 

On return, the elements of array will be sorted. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

qsort(3) 

ORIGIN 

MIPS Computer Systems 
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NAME 

rand, irand, srand - random number generator 
SYNOPSIS 

integer iseed, i, irand 

double precision x, rand 

call srand(iseed) 
i = irand( ) 
x = rand( ) 
DESCRIPTION 

Irand generates successive pseudo-random integers in the range from to 
2**15-1. rand generates pseudo-random numbers distributed in [0, 1.0]. 
Srand uses its integer argument to re-initialize the seed for successive invo- 
cations of irand and ran d. 

SEE ALSO 

rand(3C). 

ORIGIN 

AT&T V.3 
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NAME 

rename - rename a file 

SYNOPSIS 

integer function rename (from, to) 
character*^) from, to 

DESCRIPTION 

From must be the pathname of an existing file. To will become the new 
pathname for the file. If to exists, then both from and to must be the same 
type of file, and must reside on the same filesystem. If to exists, it will be 
removed first. 
The returned value will be if successful; a system error code otherwise. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

rename(2), perror(3F) 

BUGS 

Pathnames can be no longer than MAXPATHLEN as defined in 

<sys/param.h>. 



ORIGIN 
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NAME 

round: anint, dnint, nint, inint, jnint, idnint, iidnnt, jidnnt - FORTRAN 
nearest integer functions 

SYNOPSIS 

integer i 

integer*2 ii 

integer*4 ji 

real rl, r2 

real*4 r3 

double precision dpi, dp2 

real*8 dp3 

r2 = anint(rl) 

dp2 = dnint(dpl) 
dp2 = anint(dpl) 

i = nint(dpl) 

ii = inint(r3) 
ii = nint(r3) 

ji = jnint(r3) 
ji = nint(r3) 

i = idnint(dpl) 
i = nint(dpl) 

ii = iidnnt(dp3) 
ji = jidnnt(dp3) 

DESCRIPTION 

anint returns the nearest whole real number to its real argument (i.e., 
int(a+0.5) if a > 0, int(a-0.5) otherwise), dnint does the same for its 
double-precision argument, anint is the generic form of anint and dnint, 
performing the same operation and returning the data type of its argument. 
nint returns the nearest integer to its real argument, inint returns the nearest 
integer*2 to its real*4 argument, jnint returns the nearest integer*4 to its 
real*4 argument, idnint returns the nearest integer to its double precision 
argument nint is the generic form of inint Jnint and idnint. idnint is also 
the generic form for iidnnt, which returns the nearest integer*2 to its real*8 
argument, and jidnnt, which returns the nearest integer*4 to its real*8 argu- 
ment When nint or idnint is specified as an argument in a subroutine call 
or function reference, the compiler supplies either an integer*2 or integer*4 
function depending on the -i2 command line option. 
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NAME 

sign, isign, iisign, jisign, dsign- FORTRAN transfer-of-sign intrinsic func- 
tion 

SYNOPSIS 

integer i, j, k 

integer*2 iil, ii2, ii3 I 

integer*4 jil, ji2, ji3 ^ 

real rl, r2, r3 

double precision dpi, dp2, dp3 

k = isign(i, j) 
k = sign(i, j) 

ii3 = iisign(iil, ii2) 
ii3 = sign(iil, ii2) 

ji3 = jisign(jil, ji2) 
ji3 = sign(jil, ji2) 

r3 = sign(rl, r2) 

dp3 = dsign(dpl, dp2) 
dp3 = sign(dpl, dp2) 

DESCRIPTION 

isign returns the magnitude of its first argument with the sign of its second f 
argument. It accepts either integer*2 or integer*4 arguments and the result v 
is the same type, iisign and jisign take integer*2 and integer*4 arguments, 
respectively, sign and dsign are isign 9 s real and double-precision counter- 
parts, respectively. If the value of the first argument of isign, sign, or dsign 
is zero, the result is zero. The generic version is sign and will devolve to 
the appropriate type depending on its arguments. 

ORIGIN 

MIPS Computer Systems 
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NAME 

sin, dsin, csin, zsin, sind, dsind - FORTRAN sine intrinsic function 
SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 

complex*16 cdl, cd2 

real*4 r3, r4 

real*8 dp3, dp4 

r2 = sin(rl) 

dp2 = dsin(dpl) 
dp2 = sin(dpl) 

cx2 = csin(cxl) 
cx2 = sin(cxl) 

cd2 = zsin(cdl) 
cd2 = sin(cdl) 

r4 = sind(r3) 

dp4 = dsind(dp3) 
dp4 = sind(dp3) 

DESCRIPTION 

sin returns the real sine of its real argument, dsin returns the double- 
precision sine of its double-precision argument, csin returns the complex 
sine of its complex argument, zsin returns the complex* 16 sine of its com- 
plex*^ argument. The argument for these functions must be in radians and 
is treated modulo 2P. The generic sin function becomes dsin, csin, or zsin 
as required by argument type. 

sind returns the real*4 sine of its real*4 argument or the real*8 sine of its 
real*8 argument, dsind returns the real*8 sine of its real*8 argument. The 
argument for sind and dsind must be in degrees and is treated as modulo 
360. 

SEE ALSO 

tng(3M). 

ORIGIN 

MIPS Computer Systems 
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NAME 

sinh, dsinh - FORTRAN hyperbolic sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = sinh(rl) I 

dp2 = dsinh(dpl) 
dp2 = sinh(dpl) 

DESCRIPTION 

sinh returns the real hyperbolic sine of its real argument dsinh returns the 
double-precision hyperbolic sine of its double-precision argument The 
generic form sinh may be used to return a double-precision value when 
given a double-precision argument. 

SEE ALSO 

sinh(3M). 

ORIGIN 

MIPS Computer Systems 
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SLEEP(3F) Silicon Graphics SLEEP(3F) 

NAME 

sleep - suspend execution for an interval 
SYNOPSIS 

subroutine sleep (itime) 

DESCRIPTION 

Sleep causes the calling process to be suspended for itime seconds. The 
actual time can be up to 1 second less than itime due to granularity in sys- 
tem timekeeping. 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

sleep(3) 

ORIGIN 

MIPS Computer Systems 
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SQRT(3F) Silicon Graphics SQRT(3F) 

NAME 

sqrt, dsqrt, csqrt, zsqrt- FORTRAN square root intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

complex cxl, cx2 £ 

complex* 16 cdl, cd2 V 

r2 = sqrt(rl) 

dp2 = dsqrt(dpl) 
dp2 = sqrt(dpl) 

cx2 = csqrt(cxl) 
cx2 = sqrt(cxl) 

cd2 = zsqrt(cdl) 
cd2 = sqrt(cdl) 

DESCRIPTION 

sqrt returns the real square root of its real argument, dsqrt returns the 
double-precision square root of its double-precision argument. The value of 
the argument of sqrt and dsqrt must be greater than or equal to zero. 

csqrt returns the complex square root of its complex argument. The result 

of csqrt is the principle value with the real part greater than or equal to f 

zero. When the real part is zero, the imaginary part is greater than or equal V 

to zero. 

zsqrt returns the complex* 16 square root of its complex* 16 argument. 

sqrt, the generic form, will become dsqrt, csqrt, or zsqrt as required by its 

argument type. 

SEE ALSO 

exp(3M). 

ORIGIN 

MIPS Computer Systems 
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STRCMP(3F) Silicon Graphics STRCMP(3F) 

NAME 

strcmp: Ige, Igt, He, lit- FORTRAN string comparison intrinsic functions 
SYNOPSIS 

character*N al, a2 

logical 1 

1 = lge(al, a2) 
1 = lgt(al, a2) 
1 = lle(al, a2) 
1 = Ut(al, a2) 

DESCRIPTION 

These functions return .TRUE, if the inequality holds and .FALSE, other- 
wise. They return the result type logical*2 if the $log2 compile option is in 
effect; otherwise, the result type is logical*4. 

ORIGIN 

MIPS Computer Systems 
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SYSTEM(3F) Silicon Graphics SYSTEM(3F) 

NAME 

system - issue a shell command from Fortran 

SYNOPSIS 

character*N c 

call system(c) 

DESCRIPTION 

system causes its character argument to be given to sh{\) as input, as if the 
string had been typed at a terminal. The current process waits until the shell 
has completed. 

SEE ALSO 

exec(2), system(3S). 

sh(l) in the User's Reference Manual 

ORIGIN 

AT&TV.3 
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TAN(3F) Silicon Graphics TAN(3F) 

NAME 

tan, dtan, tand, dtand - FORTRAN tangent intrinsic function 
SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

real*4 r3, r4 

real*8 dp3, dp4 

r2 = tan(rl) 

dp2 = dtan(dpl) 
dp2 = tan(dpl) 

r4 = tand(r3) 

dp4 = dtand(dp3) 
dp4 = tand(dp3) 

DESCRIPTION 

tan returns the real tangent of its real argument, dtan returns the double- 
precision tangent of its double-precision argument. The argument for tan 
and dtan must be in radians and is treated modulo 2P. The generic tan 
function becomes dtan as required with a double-precision argument. 

tand returns the real*4 tangent of its real*4 argument. The argument for 
tand must be in degrees and is treated as modulo 360. dtand returns the 
real*8 tangent of its real*8 argument. The generic tand function becomes 
dtand as required with a real*8 argument. 

SEE ALSO 

trig(3M). 

ORIGIN 

MIPS Computer Systems 
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TANH(3F) Silicon Graphics TANH(3F) 



NAME 

tanh, dtanh - FORTRAN hyperbolic tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 = tanh(rl) \ 

dpi = dtanh(dpl) 
dp2 = tanh(dpl) 

DESCRIPTION 

tanh returns the real hyperbolic tangent of its real argument, dtanh returns 
the double-precision hyperbolic tangent of its double-precision argument. 
The generic form tanh may be used to return a double-precision value given 
a double-precision argument. 

SEE ALSO 

sinh(3M). 

ORIGIN 

MIPS Computer Systems 
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TIME(3F) Silicon Graphics TIME(3F) 

NAME 

time, ctime, ltime, gmtime - return system time 

SYNOPSIS 

integer function time() 

character*(*) function ctime (stime) 
integer stime 

subroutine ltime (stime, tarray) 
integer stime, tarray(9) 

subroutine gmtime (stime, tarray) 
integer stime, tarray(9) 

DESCRIPTION 

Time returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in 
seconds. This is the value of the UNIX system clock. 

Ctime converts a system time to a 24 character ASCII string. The format is 
described under ctime (3). No 'newline' or NULL will be included. 

Ltime and gmtime disect a UNIX time into month, day, etc., either for the 
local time zone or as GMT. The order and meaning of each element 
returned in tarray is described under ctime (3). 

FILES 

/usr/lib/libU77.a 

SEE ALSO 

ctime(3), itime(3F), idate(3F), fdate(3F) 

ORIGIN 

MIPS Computer Systems 



April 1990 -1- Version 3.0 



TTYNAM(3F) Silicon Graphics TTYNAM(3F) 



NAME 

ttynam, isatty - find name of a terminal port 

SYNOPSIS 

character*(*) function ttynam flunit) 

logical function isatty (lunit) 

DESCRIPTION 

Ttynam returns a blank padded path name of the terminal device associated 
with logical unit lunit. 

Isatty returns .true, if lunit is associated with a terminal device, .false, oth- 
erwise. 

FILES 

/dev/* 
/usr/lib/libU77.a 

DIAGNOSTICS 

Ttynam returns an empty string (all blanks) if lunit is not associated with a 
terminal device in directory Ydev'. 

ORIGIN 

MIPS Computer Systems 
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